0cd5d56164* [Docs] Render guides with Zensical, deploy via GitHub Pages actions phpDocumentor's guide renderer copies the markdown through mostly verbatim: relative links between pages keep pointing at `*.md` targets that do not exist in the built site, and nothing validates them, so the published guides are full of dead links. Zensical (the Material for MkDocs team's successor to MkDocs) resolves internal links against the page tree and fails the build on a broken one. `zensical build --strict` already found four dead links on the first run — three repo-relative links escaping docs/ (fixed to point at GitHub) and one wrong in-page anchor. phpDocumentor stays on for the class-level API reference only; `make docs` builds the guides into site/ and mounts the reference at site/api/, so its two header links back to the guides now target the site root. Deployment moves from pushing a gh-pages branch to the official GitHub Pages actions, and from release-only to every push on main, with pull requests building (but not deploying) so a broken link fails review instead of the site. NOTE: this needs the repository's Pages source switched to "GitHub Actions" (Settings -> Pages) once. * [Docs] Adopt the Python SDK's documentation look and feel The docs site now uses the same theme configuration as https://py.sdk.modelcontextprotocol.io/ so the language SDKs read as one set of docs: the MCP mark as logo and favicon, Inter/JetBrains Mono, the black/slate palette with a three-way (system/light/dark) toggle, instant navigation, code copy/annotate, and a right-hand table of contents. The markdown extension set is widened to the same list (tabbed blocks, task lists, footnotes, emoji/icons, mermaid fences), which the content restructure builds on. Styling is otherwise stock: no custom stylesheet, and Zensical's own `modern` theme variant, pinned explicitly rather than left to the default. The one departure is code highlighting, which is broken out of the box here: Pygments only highlights PHP after a `<?php` tag, so the guides — whose code blocks are almost all fragments — rendered as flat plain text. The `php` lexer is extended with `startinline`, and complete-file blocks use a `php-file` lexer that keeps the literal open tag highlighted. * [Docs] Restructure the guides into task-oriented sections The guides were ten flat pages, each opening with a hand-maintained table of contents and each mixing several audiences: `mcp-elements.md` covered tools, prompts, schema generation and handler-side logging, `transports.md` covered both transports plus framework integration, and `server-builder.md` covered configuration, sessions and custom message handlers. They are now split along the same lines as the Python SDK's documentation (https://py.sdk.modelcontextprotocol.io/), one topic per page: Get started installation, first server, the Inspector Servers tools, resources, resource templates, prompts, completions, schema generation, registration Inside your handler the ClientGateway, logging Running your server builder, STDIO, HTTP, framework integration, sessions, authorization Clients connecting, transports, capabilities, server-initiated requests, error handling Advanced events, protocol extensions, custom message handlers Prose is carried over as-is apart from the seams; what is new is the landing page and one index page per section, which say what the section is for and where to go next, so no page is a dead end. The per-page "Table of Contents" lists are gone — the theme renders one from the headings — and GitHub's `> [!IMPORTANT]` blockquotes became admonitions, which Zensical renders as callouts rather than plain quotes. Every code sample and factual claim was then checked against src/ and the runnable examples, which turned up long-standing errors in the carried-over prose. Samples that could not run: a prompt using a `system` role (MCP has only user/assistant), `Mcp\Schema\PromptMessage` (it is under `Schema\Content`) constructed with an array instead of a single content object, `Mcp\Capability\Prompt\Completion\ProviderInterface` (it is `Mcp\Capability\Completion\ProviderInterface`), `new EmbeddedResource(type:, resource: [...])` (neither parameter exists), a `: resource` return type (not a PHP type), `#[McpResource]` with a `{path}` variable (that is a template), a stray quote in the builder example, a `middlewares:` argument (it is `middleware:`), and `getRequest()->getAttribute()` in the OAuth guide (no such method — the values arrive on the request meta). Claims corrected: sampling's `system_prompt` option (it is `systemPrompt`), `SampleMessage` (it is `SamplingMessage`), `Notification` called an interface (abstract class), "parameter order matters" for URI templates (bound by name), full RFC 6570 support (only simple `{var}`), the tool description fallback chain, `void` returning empty content, a non-zero STDIO exit code, `ErrorEvent` being null for parse errors, handlers being "prepended", `Psr16StoreSession`, and PSR-3 log context being sent to the client (it is dropped). Sixteen `examples/` paths were missing their `server/` segment. README, the OAuth ADR and one source comment now point at the published site instead of at markdown files that moved. * [Docs] Run the docs workflow unfiltered, keep README links relative The `paths:` filters were mostly noise: `src/**` had to be in the list for the phpDocumentor build, which meant the workflow ran on nearly every PR anyway. They also missed two real inputs — `.phpdoc/template/**` and `composer.lock` — so a template tweak or a phpDocumentor bump could change the rendered site without triggering a build. README links go back to relative repo paths. The README is not part of the Zensical site (`docs_dir` is `docs/`), so those links are only ever resolved by GitHub and Packagist, where absolute URLs break in-repo navigation for no gain. The site pointer and the generated API reference stay absolute. * [Docs] Adopt the doc changes that landed on main into the new structure Twelve commits landed while the restructure was open, seven of them touching the flat guides this branch replaces. Renames merged on their own; the three files that were split apart needed their new sections placed by hand: - Connection retries, protocol version negotiation, sampling with tools and roots from `client.md` into `client/connecting.md` and `client/server-requests.md` - `ResourceLink` and structured output from `mcp-elements.md` into `servers/tools.md` - Protocol version negotiation from `server-builder.md` into `run/server-builder.md` The `setMaxRetries()` note claiming the value is never acted on is gone — #413 implemented it. Callouts became admonitions and cross-links were repointed at the new paths, as everywhere else in this branch. * [Docs] Document the elicitation and roots client examples Both were missing from the examples guide: the elicitation client predates this branch, the roots client arrived with #395. * [Docs] Fold the 2026-07-28 lifecycle into the new structure Main's stateless-lifecycle.md becomes a docs/lifecycle/ section, and the pages main touched — deprecations, the middleware split, the client's modern era — land where the restructure moved them. * [Docs] Link the Inspector to its documentation, not its repo * [Docs] Distribute the 2026-07-28 material into the task sections The Python and TypeScript SDKs file each feature where the task lives and keep only an era comparison on its own page. Follow them: input-required moves next to the other handler concerns, caching, subscriptions and era routing to "Running your server", and one Protocol versions page carries the rest. * [Docs] Move protocol version negotiation onto the Protocol versions page The builder page keeps the setProtocolVersion() knob and links out; how a revision is agreed now sits beside the era it belongs to. * [Docs] Slim the README to a funnel, turn Examples into an index * [Docs] Fix the code samples and API listings flagged by the audit * [Docs] Link the negotiation spec section at latest, not draft
97 lines
5.6 KiB
Markdown
97 lines
5.6 KiB
Markdown
# 0001 — The MCP server is an OAuth Resource Server, not an Authorization Server
|
|
|
|
- Status: Accepted
|
|
- Date: 2026-06-15
|
|
|
|
## Context
|
|
|
|
OAuth 2.1 defines three distinct roles:
|
|
|
|
| Role | What it does | Status in this SDK | Scope |
|
|
|------|--------------|--------------------|-------|
|
|
| Resource Server | Validates incoming bearer tokens, serves Protected Resource Metadata (RFC 9728), emits `WWW-Authenticate` | Shipped (`AuthorizationMiddleware`, `JwtTokenValidator`, `ProtectedResourceMetadata`) | **IN scope** |
|
|
| Delegation / proxy to an upstream AS | Forwards `/authorize` and `/token` to your existing IdP | Shipped (`OAuthProxyMiddleware`) | **IN scope — delegation ONLY** |
|
|
| Authorization Server / Identity Provider (IdP) | Mints its own tokens, registers clients, runs login and consent | Absent | **OUT of scope** |
|
|
|
|
The SDK repeatedly receives pull requests that move it toward becoming a full OAuth 2.1
|
|
**authorization server** — asking the MCP server to mint its own access and refresh tokens,
|
|
register clients, and run login and consent flows, that is, to become an Identity Provider.
|
|
The most explicit example is [#373](https://github.com/modelcontextprotocol/php-sdk/pull/373)
|
|
("[Server] Add native OAuth 2.1 authorization server", ~3,400 lines across 50+ files), but the
|
|
direction has crept in incrementally rather than in one PR.
|
|
|
|
A contributing factor is that the SDK already exposes the *authorization-server endpoints in
|
|
proxy form*, and that surface has grown:
|
|
[#221](https://github.com/modelcontextprotocol/php-sdk/pull/221) added the OAuth resource-server
|
|
middleware, and [#269](https://github.com/modelcontextprotocol/php-sdk/pull/269) added Dynamic
|
|
Client Registration (RFC 7591). Today `OAuthProxyMiddleware` answers `/authorize`, `/token`, and
|
|
`/.well-known/oauth-authorization-server`, and DCR endpoints exist. The shape of that surface
|
|
invites contributors to "finish the job" by backing those endpoints with a real token issuer.
|
|
It is not scaffolding to be completed — it is a delegating proxy, and that is the whole of its
|
|
intent.
|
|
|
|
## Decision
|
|
|
|
**The MCP server is an OAuth 2.1 Resource Server that MAY delegate to an upstream
|
|
authorization server. It will NOT issue tokens or act as an Identity Provider.**
|
|
|
|
Concretely:
|
|
|
|
- The SDK validates bearer tokens, serves RFC 9728 Protected Resource Metadata, and emits
|
|
`WWW-Authenticate` challenges. This is the Resource Server role and is fully supported.
|
|
- The SDK MAY delegate `/authorize` and `/token` to an upstream authorization server via
|
|
`OAuthProxyMiddleware`. This is delegation only: the middleware redirects the browser to
|
|
the upstream `/authorize` endpoint and proxies `/token` requests to the upstream token
|
|
endpoint. It never mints, signs, stores, or rotates tokens of its own.
|
|
- The SDK will NOT implement an authorization server: no token issuance, no token signing or
|
|
key management, no login UI, no consent UI, no authorization-code or refresh-token storage,
|
|
no first-party Dynamic Client Registration acting as an issuer.
|
|
|
|
Pull requests that add authorization-server / IdP behavior are declined by reference to this
|
|
ADR.
|
|
|
|
## Rationale
|
|
|
|
- **Security liability.** Issuing tokens means owning signing-key generation, storage, and
|
|
rotation; authorization-code and refresh-token persistence; refresh-token rotation and
|
|
replay detection; and consent. A defect in any of these is a credential-issuance
|
|
vulnerability affecting every consumer of the SDK. This is precisely the surface an MCP SDK
|
|
should not own.
|
|
- **RFC footprint.** A correct authorization server must implement and keep current with
|
|
RFC 6749 (OAuth 2.0), RFC 7591 (Dynamic Client Registration), RFC 8414 (Authorization
|
|
Server Metadata), PKCE (RFC 7636), and refresh-token rotation guidance, among others. That
|
|
is an open-ended maintenance and conformance burden far outside the SDK's purpose.
|
|
- **Mature implementations already exist.** Token issuance is a solved problem.
|
|
`league/oauth2-server` provides it as a PHP library, and every production IdP — Keycloak,
|
|
Auth0, Microsoft Entra ID, Okta — provides it as a service. Re-implementing it inside an
|
|
MCP SDK adds risk without adding value.
|
|
|
|
## Boundary statement
|
|
|
|
`OAuthProxyMiddleware` **delegates** to an upstream IdP. It is **not** authorization-server
|
|
scaffolding to be completed. Backing its `/authorize` and `/token` endpoints with a
|
|
first-party token issuer is out of scope and will be declined.
|
|
|
|
## Consequences
|
|
|
|
- The supported authorization architecture is: an external authorization server (your IdP or
|
|
`league/oauth2-server` running in your own application) issues tokens; the MCP server
|
|
validates them as a Resource Server and optionally proxies the OAuth flow to that upstream.
|
|
- Contributors get a single, citable ruling for why authorization-server PRs are declined,
|
|
reducing repeated large-PR churn.
|
|
- Resource Server and proxy/delegation features remain welcome and supported.
|
|
|
|
## Alternatives / what to do instead
|
|
|
|
If you need an authorization server (token issuance, client registration, login, consent), do
|
|
**not** add it to this SDK. Instead:
|
|
|
|
- **Front the MCP server with an existing IdP** — Keycloak, Auth0, Microsoft Entra ID, or
|
|
Okta. Point `JwtTokenValidator` and `ProtectedResourceMetadata` at that issuer, and
|
|
optionally use `OAuthProxyMiddleware` to delegate `/authorize` and `/token` to it.
|
|
- **Run `league/oauth2-server` in your own application**, behind the SDK's existing proxy and
|
|
validator seams. The MCP server validates the tokens it issues; it does not issue them
|
|
itself.
|
|
|
|
See [`../docs/run/authorization.md`](../docs/run/authorization.md) for the supported Resource Server
|
|
and delegation setup.
|