Skip to content

docs(self-host): MCP_URL also turns on OAuth issuer identification - #264

Open
giladresisi wants to merge 1 commit into
mainfrom
docs/mcp-url-issuer-identification
Open

giladresisi wants to merge 1 commit into
mainfrom
docs/mcp-url-issuer-identification

Conversation

@giladresisi

@giladresisi giladresisi commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

⚠️ Merge only after gitroomhq/postiz-app#2092 is merged and deployed

This page describes behavior that ships with that PR. Merging earlier would document an MCP_URL effect the released backend does not have yet.

What kind of change does this PR introduce?

Documentation (self-host configuration reference). Rewrites the MCP_URL row in self-host/configuration/reference.mdx: the value is the public URL of the MCP server including https:// (the backend URL in a standard install); set on the backend too, it turns on OAuth issuer identification (RFC 9207), which Codex CLI needs when FRONTEND_URL and NEXT_PUBLIC_BACKEND_URL differ in domain or port; it must not be a second hostname proxying to the same backend; an invalid value is ignored and reported at startup; leaving it unset keeps the feature off. No other row or page changes.

Why was this change needed?

Companion to gitroomhq/postiz-app#2092, where MCP_URL stops being frontend-only: the backend uses it to advertise RFC 9207 issuer identification and to build the iss parameter on authorization redirects. Self-hosters who already set MCP_URL for the frontend get the feature turned on, so the row has to say what the value must be and what breaks it.

Other information:

The behavior described here was verified against a local install of that PR: a valid MCP_URL enables issuer identification and Codex CLI signs in; a value without a scheme is reported at startup as "MCP_URL is not a valid URL" and leaves the feature off; with MCP_URL unset nothing changes.

QA

  1. Open the self-host configuration reference page and find MCP_URL under "Public API & MCP"
  2. Confirm the row says to include https://, to use the backend URL in a standard install, that Codex CLI needs it only when the frontend and backend differ in domain or port, that a second hostname proxying to the same backend breaks the sign-in, that an invalid value is ignored and reported at startup, and that leaving it unset keeps it off
  3. Confirm this PR is merged only after feat(oauth): advertise RFC 9207 issuer identification postiz-app#2092 is deployed

Checklist:

  • I have filled in the QA section above with real steps to verify this change.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Clarified how MCP_URL affects the displayed endpoint and OAuth issuer identification, including guidance for standard installs and setups with different frontend and backend addresses.
    • Documented that invalid values are ignored and reported at startup, while leaving the setting unset disables issuer identification.

MCP_URL is now read by the backend too: when set to a valid URL it turns
on RFC 9207 issuer identification for the MCP OAuth server, which Codex
CLI needs when the frontend and backend differ in domain or port. The
row explains what value to use, that a second hostname proxying to the
same backend breaks issuer validation, that an invalid value is ignored
and reported at startup, and that leaving it unset keeps it off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The configuration reference expands the MCP_URL description to cover frontend endpoint display, backend OAuth issuer identification, URL guidance, and startup behavior for invalid or unset values.

Changes: MCP_URL configuration reference

Layer / File(s) Summary
Document MCP_URL behavior
self-host/configuration/reference.mdx
The MCP_URL description now covers backend OAuth issuer identification, its use by Codex CLI when frontend and backend origins differ, URL guidance, and invalid or unset values.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: Minimal · up to 4f79d

This documentation-only change clarifies how to set MCP_URL for OAuth issuer identification. It is consistent with the self-host docs and has no concrete merge risk, provided the companion application change is merged and deployed first, as the PR states.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the docs change to the MCP_URL row and the behavior it adds. The changeset documents that MCP_URL enables RFC 9207 OAuth issuer identification when set on the backend, so the title mat…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the docs change to the MCP_URL row and the behavior it adds. The changeset documents that MCP_URL enables RFC 9207 OAuth issuer identification when set on the backend, so the title matches the main change. The title uses the conventional docs(scope) prefix and is specific enough for a teammate scanning history.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 9dddfc22-0e4b-4ba7-80e0-58330947cff6
Commits

Reviewing files that changed from the base of the PR and between 3280a17 and 4f79d8f.

Files selected for processing: 1

  • self-host/configuration/reference.mdx

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant