410 changed files with 4484 additions and 31710 deletions
--- a/.gitattributes
+++ b/.gitattributes
@ -5,8 +5,6 @@
 /tests export-ignore
 /.php-cs-fixer.dist.php export-ignore
 /Makefile export-ignore
-/mkdocs.yml export-ignore
-/requirements-docs.txt export-ignore
 /phpdoc.dist.xml
 /phpstan* export-ignore
 /phpunit.xml.dist export-ignore
--- a/.github/workflows/conformance-weekly.yaml
+++ b/.github/workflows/conformance-weekly.yaml
@ -1,8 +1,13 @@
 name: conformance-weekly

-# Tracks the newest published @modelcontextprotocol/conformance; the
-# on:pull_request pipeline pins an exact version instead. Also publishes
-# score badges to the orphan `badges` branch, consumed by the README.
+# Runs the MCP conformance suite weekly against the latest
+# @modelcontextprotocol/conformance release. The on:pull_request pipeline
+# pins to whatever version is available at PR time; this schedule catches
+# upstream releases that add scenarios between PRs.
+#
+# It also scores each run and publishes the client/server pass-rate as
+# shields.io endpoint JSON to the orphan `badges` branch (consumed by the
+# README); that branch is created on the first run.
 on:
  schedule:
    - cron: '0 6 * * 1' # Mondays 06:00 UTC
@ -14,23 +19,11 @@ permissions:

 jobs:
  server:
-    name: conformance / server (${{ matrix.spec-version }}, ${{ matrix.dist-tag }})
+    name: conformance / server (latest)
    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - spec-version: '2025-11-25'
-            dist-tag: latest
-            path: '/'
-            baseline: conformance-baseline-2025-11-25.yml
-          - spec-version: '2026-07-28'
-            dist-tag: alpha
-            path: '/'
-            baseline: conformance-baseline-2026-07-28.yml
    steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-node@v7
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
        with:
          node-version: '22'
      - run: composer install --prefer-dist --no-progress --no-interaction
@ -42,16 +35,10 @@ jobs:
          sleep 5
      - name: Run conformance tests
        working-directory: ./tests/Conformance
-        run: >-
-          npx --yes @modelcontextprotocol/conformance@${{ matrix.dist-tag }} server
-          --url http://localhost:8000${{ matrix.path }}
-          --suite all
-          --spec-version ${{ matrix.spec-version }}
-          --expected-failures ${{ matrix.baseline }}
-          --output-dir results
+        run: npx --yes @modelcontextprotocol/conformance@latest server --url http://localhost:8000/ --expected-failures conformance-baseline.yml --output-dir results
      - name: Generate score badge
        if: always()
-        run: php tests/Conformance/score.php server ${{ matrix.spec-version }}
+        run: php tests/Conformance/score.php server
      - name: Show docker logs on failure
        if: failure()
        run: docker compose -f tests/Conformance/Fixtures/docker-compose.yml logs
@ -59,7 +46,7 @@ jobs:
        if: failure()
        uses: actions/upload-artifact@v7
        with:
-          name: conformance-server-results-${{ matrix.spec-version }}
+          name: conformance-server-results
          path: |
            tests/Conformance/logs
            tests/Conformance/results
@ -67,50 +54,34 @@ jobs:
        if: always()
        uses: actions/upload-artifact@v7
        with:
-          name: badge-server-${{ matrix.spec-version }}
-          path: tests/Conformance/server-conformance-${{ matrix.spec-version }}.json
+          name: server-badge
+          path: tests/Conformance/server-conformance.json

  client:
-    name: conformance / client (${{ matrix.spec-version }}, ${{ matrix.dist-tag }})
+    name: conformance / client (latest)
    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - spec-version: '2025-11-25'
-            dist-tag: latest
-            baseline: conformance-baseline-2025-11-25.yml
-          - spec-version: '2026-07-28'
-            dist-tag: alpha
-            baseline: conformance-baseline-2026-07-28.yml
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          coverage: none
-      - uses: actions/setup-node@v7
+      - uses: actions/setup-node@v6
        with:
          node-version: '22'
      - run: composer install --prefer-dist --no-progress --no-interaction
      - run: mkdir -p tests/Conformance/logs
      - name: Run conformance tests
        working-directory: ./tests/Conformance
-        run: >-
-          npx --yes @modelcontextprotocol/conformance@${{ matrix.dist-tag }} client
-          --command "php ${{ github.workspace }}/tests/Conformance/client.php"
-          --suite all
-          --spec-version ${{ matrix.spec-version }}
-          --expected-failures ${{ matrix.baseline }}
-          --output-dir results
+        run: npx --yes @modelcontextprotocol/conformance@latest client --command "php ${{ github.workspace }}/tests/Conformance/client.php" --suite all --expected-failures conformance-baseline.yml --output-dir results
      - name: Generate score badge
        if: always()
-        run: php tests/Conformance/score.php client ${{ matrix.spec-version }}
+        run: php tests/Conformance/score.php client
      - name: Upload conformance results
        if: failure()
        uses: actions/upload-artifact@v7
        with:
-          name: conformance-client-results-${{ matrix.spec-version }}
+          name: conformance-client-results
          path: |
            tests/Conformance/logs
            tests/Conformance/results
@ -118,18 +89,17 @@ jobs:
        if: always()
        uses: actions/upload-artifact@v7
        with:
-          name: badge-client-${{ matrix.spec-version }}
-          path: tests/Conformance/client-conformance-${{ matrix.spec-version }}.json
+          name: client-badge
+          path: tests/Conformance/client-conformance.json

  notify:
    name: Open issue on failure
    runs-on: ubuntu-latest
    needs: [server, client]
-    if: failure()
+    if: failure() && github.event_name == 'schedule'
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      GH_REPO: ${{ github.repository }}
-      EVENT_NAME: ${{ github.event_name }}
      RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
    steps:
      - name: File or comment tracking issue
@ -141,27 +111,31 @@ jobs:
            gh issue create \
              --title '[conformance] Weekly conformance run failed' \
              --label conformance-weekly \
-              --body "Conformance against the newest published \`@modelcontextprotocol/conformance\` failed.
+              --body "Weekly conformance against \`@modelcontextprotocol/conformance@latest\` failed.

          - Run: $RUN_URL
-          - Trigger: $EVENT_NAME
-          - Date: $(date -u +%FT%TZ)
+          - Triggered: $(date -u +%FT%TZ)

-          Upstream likely published a release whose scenarios the SDK does not satisfy. Either fix the SDK, update the conformance fixtures, or add the new failure to the matching \`tests/Conformance/conformance-baseline-<spec-version>.yml\`."
+          Upstream likely published a release whose scenarios the SDK does not satisfy. Either fix the SDK, update the conformance fixtures, or add the new failure to \`tests/Conformance/conformance-baseline.yml\`."
          fi

  publish:
    name: Publish conformance badges
    runs-on: ubuntu-latest
    needs: [server, client]
+    # Publish even when the suite regressed (the badge should reflect reality);
+    # skip on forks, which cannot push the `badges` branch.
    if: ${{ !cancelled() && github.repository == 'modelcontextprotocol/php-sdk' }}
    steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@v6
      - uses: actions/download-artifact@v8
        with:
-          pattern: badge-*
+          name: server-badge
+          path: badges-in
+      - uses: actions/download-artifact@v8
+        with:
+          name: client-badge
          path: badges-in
-          merge-multiple: true
      - name: Publish to badges branch
        run: |
          git config user.name "github-actions[bot]"
@ -176,8 +150,7 @@ jobs:
            git -C badges-wt rm -rf --quiet . >/dev/null 2>&1 || true
          fi

-          rm -f badges-wt/server-conformance.json badges-wt/client-conformance.json
-          cp badges-in/*.json badges-wt/
+          cp badges-in/server-conformance.json badges-in/client-conformance.json badges-wt/

          cd badges-wt
          git add -A
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@ -1,29 +1,19 @@
-name: Documentation
-
-# The site is built by `make docs`: Zensical renders the guides under docs/
-# (see mkdocs.yml) and phpDocumentor renders the API reference into /api/.
-# Pull requests build only — the build is strict, so a broken internal link
-# fails CI instead of shipping a dead link to the site.
+name: Deploy Documentation

 on:
-  push:
-    branches: [main]
-  pull_request:
+  release:
+    types: [published]
  workflow_dispatch:

 permissions:
-  contents: read
-
-concurrency:
-  group: docs-${{ github.ref }}
-  cancel-in-progress: true
+  contents: write

 jobs:
-  build:
+  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
@ -31,33 +21,15 @@ jobs:
          php-version: '8.4'
          coverage: "none"

-      - name: Install Composer dependencies
+      - name: Install Composer
        uses: "ramsey/composer-install@v4"

-      - name: Install uv
-        uses: astral-sh/setup-uv@v10.1.0
-        with:
-          enable-cache: true
-
-      - name: Build documentation
+      - name: Generate Documentation
        run: make docs

-      - name: Upload Pages artifact
-        uses: actions/upload-pages-artifact@v5
+      - name: Deploy to gh-pages branch
+        uses: peaceiris/actions-gh-pages@v4
        with:
-          path: ./site
-
-  deploy:
-    needs: build
-    if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v5
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./.phpdoc/build
+          enable_jekyll: false
--- a/.github/workflows/pipeline.yaml
+++ b/.github/workflows/pipeline.yaml
@ -5,10 +5,6 @@ permissions:
  contents: read
  pull-requests: write

-env:
-  # Pinned exact version; conformance-weekly.yaml tracks upstream releases.
-  CONFORMANCE_PKG: "@modelcontextprotocol/conformance@0.2.0-alpha.11"
-
 jobs:
  unit:
    runs-on: ubuntu-latest
@ -36,7 +32,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
@ -53,33 +49,11 @@ jobs:
      - name: Tests
        run: vendor/bin/phpunit --testsuite=unit

-  integration:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        php: ['8.1', '8.2', '8.3', '8.4', '8.5']
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v7
-
-      - name: Setup PHP
-        uses: shivammathur/setup-php@v2
-        with:
-          php-version: ${{ matrix.php }}
-          coverage: "none"
-
-      - name: Install Composer
-        uses: "ramsey/composer-install@v4"
-
-      - name: Tests
-        run: vendor/bin/phpunit --testsuite=integration
-
  inspector:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
@ -88,7 +62,7 @@ jobs:
          coverage: "none"

      - name: Setup Node
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@v6
        with:
          node-version: '22'

@ -99,25 +73,14 @@ jobs:
        run: vendor/bin/phpunit --testsuite=inspector

  conformance-server:
-    name: conformance / server (${{ matrix.spec-version }})
+    name: conformance / server
    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - spec-version: '2025-11-25'
-            path: '/'
-            baseline: conformance-baseline-2025-11-25.yml
-          - spec-version: '2026-07-28'
-            path: '/'
-            baseline: conformance-baseline-2026-07-28.yml
-
    steps:
      - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6

      - name: Setup Node
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@v6
        with:
          node-version: '22'

@ -133,12 +96,7 @@ jobs:

      - name: Run conformance tests
        working-directory: ./tests/Conformance
-        run: >-
-          npx --yes ${{ env.CONFORMANCE_PKG }} server
-          --url http://localhost:8000${{ matrix.path }}
-          --suite all
-          --spec-version ${{ matrix.spec-version }}
-          --expected-failures ${{ matrix.baseline }}
+        run: npx @modelcontextprotocol/conformance server --url http://localhost:8000/ --expected-failures conformance-baseline.yml

      - name: Show logs on failure
        if: failure()
@ -166,20 +124,11 @@ jobs:
        run: docker compose -f tests/Conformance/Fixtures/docker-compose.yml down

  conformance-client:
-    name: conformance / client (${{ matrix.spec-version }})
+    name: conformance / client
    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - spec-version: '2025-11-25'
-            baseline: conformance-baseline-2025-11-25.yml
-          - spec-version: '2026-07-28'
-            baseline: conformance-baseline-2026-07-28.yml
-
    steps:
      - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
@ -188,7 +137,7 @@ jobs:
          coverage: "none"

      - name: Setup Node
-        uses: actions/setup-node@v7
+        uses: actions/setup-node@v6
        with:
          node-version: '22'

@ -200,12 +149,7 @@ jobs:

      - name: Run client conformance tests
        working-directory: ./tests/Conformance
-        run: >-
-          npx --yes ${{ env.CONFORMANCE_PKG }} client
-          --command "php ${{ github.workspace }}/tests/Conformance/client.php"
-          --suite all
-          --spec-version ${{ matrix.spec-version }}
-          --expected-failures ${{ matrix.baseline }}
+        run: npx @modelcontextprotocol/conformance client --command "php ${{ github.workspace }}/tests/Conformance/client.php" --suite all --expected-failures conformance-baseline.yml

      - name: Show logs on failure
        if: failure()
@ -224,7 +168,7 @@ jobs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@v7
+        uses: actions/checkout@v6

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
@ -244,7 +188,5 @@ jobs:
      - name: PHPStan
        run: vendor/bin/phpstan analyse

-      # Only the phpDocumentor half: this job is PHP-only, and the Zensical
-      # guides are built (strictly) by the Documentation workflow.
      - name: Documentation
-        run: make docs-api
+        run: make docs
--- a/.gitignore
+++ b/.gitignore
@ -8,14 +8,10 @@ examples/**/cache
 examples/**/sessions
 tests/Conformance/client-conformance.json
 tests/Conformance/server-conformance.json
-tests/Conformance/results*
+tests/Conformance/results
 tests/Conformance/sessions
 tests/Conformance/logs/*.log

 # phpDocumentor
 .phpdoc/build/
 .phpdoc/cache/
-
-# Documentation site (make docs)
-/site/
-/.cache/
--- a/.phpdoc/template/base.html.twig
+++ b/.phpdoc/template/base.html.twig
@ -2,7 +2,7 @@

 {% set topMenu = {
    "menu": [
-        { "name": "Guides", "url": "/"},
+        { "name": "Guides", "url": "docs/index.html"},
        { "name": "Specification", "url": "https://modelcontextprotocol.io/" }
    ],
    "social": [
--- a/.phpdoc/template/components/header-title.html.twig
+++ b/.phpdoc/template/components/header-title.html.twig
@ -1,5 +1,5 @@
 <h1 class="phpdocumentor-title">
-    <a href="/" class="phpdocumentor-title__link">
+    <a href="{{ path('/docs/index.html') }}" class="phpdocumentor-title__link">
        <svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 195 195" fill="none">
            <path d="M25 97.8528L92.8823 29.9706C102.255 20.598 117.451 20.598 126.823 29.9706V29.9706C136.196 39.3431 136.196 54.5391 126.823 63.9117L75.5581 115.177" stroke="black" stroke-width="12" stroke-linecap="round"/>
            <path d="M76.2653 114.47L126.823 63.9117C136.196 54.5391 151.392 54.5391 160.765 63.9117L161.118 64.2652C170.491 73.6378 170.491 88.8338 161.118 98.2063L99.7248 159.6C96.6006 162.724 96.6006 167.789 99.7248 170.913L112.331 183.52" stroke="black" stroke-width="12" stroke-linecap="round"/>
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -2,59 +2,6 @@

 All notable changes to `mcp/sdk` will be documented in this file.

-0.9.0
-----
-
-* [BC Break] Remove the `providerClass` argument of `#[CompletionProvider]`. Use `provider:`, which takes the same class-string and is now the first positional argument.
-* Add `HttpTransport::getSessionId()` to read the server-minted `Mcp-Session-Id`: a request-scoped caller can persist it and pass it back through the constructor's `$headers` on a later transport. Always `null` on `2026-07-28`, which removed protocol-level sessions.
-* Fix OIDC discovery rejecting issuers with a trailing slash (e.g. Authentik, Auth0).
-
-0.8.0
-----
-
-* Support for MCP spec version 2026-07-28 incl. stateless HTTP transport
-  * Negotiate the protocol revision during `initialize`: the server counter-offers a revision it supports and the client fails the handshake instead of continuing on an unagreed one. Adds `Client::getProtocolVersion()`.
-  * Serve both protocol eras from one endpoint: `StreamableHttpTransport` classifies each request (`InboundClassifier`) and routes it to the matching dispatcher, so one URL answers modern and handshake-era clients alike. `Builder::withoutModernEra()` opts out, `Builder::setModernVersions()` narrows the modern leg.
-  * Speak the lifecycle from the client: `Client` opens with `server/discover`, stamps `_meta` with version, capabilities and client info, and sends the `Mcp-Method`/`Mcp-Name`/`Mcp-Param-*` headers (via `Client\Stateless\ToolCatalog`). `Schema\Wire\McpHeader` holds the shared header names.
-  * Add multi round-trip requests (SEP-2322): a handler returning `InputRequiredResult` yields `resultType: "input_required"` with an opaque, signed `requestState` (`RequestStateCodec`, key via `Builder::setRequestState()`); the client retries with `inputResponses`, read through `RequestContext::getInputContext()` and its typed `elicitResult()`/`samplingResult()`/`rootsResult()`. On the client, `InputRequestResolver` answers such results automatically from the host's elicitation, sampling and roots handlers.
-  * Serve `ClientGateway::elicit()`/`elicitUrl()` on every revision: where the client cannot be asked mid-request, `Server\Stateless\ElicitationReplay` turns the ask into `input_required` and resumes once re-sent — the handler is entered once per ask. `InputRequiredShim` does the reverse for handshake-era clients. `sample()`/`listRoots()` raise a `LogicException` on `2026-07-28`, which removed them.
-  * Run stateless handlers in a fiber so `$gateway->progress()`/`log()` stream over SSE when the handler emits something and the client accepts `text/event-stream`; honour `io.modelcontextprotocol/logLevel` (SEP-2575). Adds `LoggingLevel::severity()`/`isAtLeast()`.
-  * Deliver notifications on `subscriptions/listen` (SEP-2575) via `NotificationBusInterface` — `InMemoryNotificationBus` for persistent runtimes, `Psr16NotificationBus` for PHP-FPM — set with `Builder::setNotificationBus()`; `Builder::setSubscriptionLifetime()` replaces the hard-coded 30s ceiling.
-  * Validate the standard request headers (SEP-2243) with `StandardHeaderValidator` (`Builder::setHeaderValidator()`), answering `-32020` when they contradict the body.
-  * Add `Wire\CachePolicy` (`Builder::setCachePolicy()`) for SEP-2549 caching hints; defaults to `ttlMs: 0, cacheScope: private`. A `ReadResourceResult` may override with its own values.
-  * Carry W3C trace context (SEP-414): `traceparent`/`tracestate`/`baggage` from `_meta` are exposed via `RequestContext::getTraceContext()` and echoed onto the request's notifications.
-  * Close the schema gaps for `2025-06-18`/`2025-11-25` and add the `2026-07-28` surface (SEP-2106): url-mode elicitation (`ClientGateway::elicitUrl()`/`supportsElicitationUrl()`), `Implementation::title`, and `outputSchema`/`structuredContent` accepting any JSON value.
-  * Deprecate Roots, Sampling and Logging (SEP-2577, earliest removal `2027-07-28`); they keep working but trigger a deprecation notice.
-  * [BC Break] Answer a not-found subject with `-32602` instead of `-32002` (SEP-2164): `resources/read` picks the code by revision (`-32602` from `2026-07-28` on), `prompts/get`, `completion/complete` and `tools/call` switch on every revision. Adds `ProtocolVersion::usesInvalidParamsForResourceNotFound()`.
-  * [BC Break] A list-shaped tool result is only sent as `structuredContent` on `2026-07-28`+; older revisions keep the JSON-encoded value in `content`.
-* [BC Break] Add the extensions framework (SEP-2133) MCP Apps sits on: `ExtensionInterface::getId()` returns an `ExtensionIdentifier` value object, and the interface gains `getMessages()`/`getRequestHandlers()` (extend `AbstractExtension` to skip both). `MessageFactory::make()` takes an `$additional` message list; `RequestHandlerInterface`'s result template is covariant. `ServerExtensionInterface` is replaced by the side-agnostic `Schema\Extension\ExtensionInterface`.
-* Add client-side extension negotiation: `ClientGateway::supportsExtension()`, `Client\Builder::enableExtension()`, `ClientCapabilities::withExtensions()`.
-* Add sampling-with-tools: sampling requests can carry tools and tool-choice preferences, messages support tool-use/tool-result blocks, and clients advertise `sampling.context`/`sampling.tools` (`ClientGateway::supportsSamplingTools()`/`supportsSamplingContext()`). Requests violating the tool-flow rules are rejected with a JSON-RPC error.
-* [BC Break] `SamplingMessage::$content` and `CreateSamplingMessageResult::$content` may be a list of content blocks — use `getContentBlocks()`. `CreateSamplingMessageResult` rejects roles other than `assistant` and empty content.
-* Add client-side Roots support (`RootsCallbackInterface`, `Client::sendRootsListChanged()`) and server-side `ClientGateway::listRoots()`/`supportsRoots()`/`supportsSampling()`.
-* Add `Schema\Content\ResourceLink` to reference a resource by URI in tool results and prompt messages.
-* [BC Break] `Schema\JsonRpc\Error` accepts `null` as `$id`; an unreadable id now omits the member instead of sending `"id": ""`. `MessageFactory` decodes a missing or null id as an id-less error.
-* Preserve the request `id` on an invalid-but-parseable message (`-32600`) via `InvalidInputMessageException::getRequestId()`.
-* [BC Break] Drop the SDK-only name pattern on `ResourceDefinition`/`ResourceTemplate` `$name`; the spec allows any string.
-* Log expected tool failures (`ToolCallException`) at debug level instead of error.
-* Add `annotations` to `ImageContent`.
-* Fix empty tool/resource schemas serializing as `[]` instead of `{}`.
-* Fix `PromptResultFormatter` dropping `annotations`, `_meta` and `mimeType` for plain-array content.
-
-0.7.0
-----
-
-* Add client-side elicitation support: `ElicitationCallbackInterface`, `ElicitationRequestHandler`, and `ElicitationException` let clients respond to server elicitation requests.
-* Defer element loading to the first registry read: loaders now run at request time (first `has*`/`get*` call) instead of eagerly at `Builder::build()`, fixing empty registries under persistent runtimes (e.g. FrankenPHP worker mode) where a loader's data source is not ready at build time. Adds `Builder::setLazyLoading()` (default on), a public `Registry::load()`, and an optional `LoaderInterface` constructor argument on `Registry`.
-* [BC Break] Element loading is lazy by default: loader failures now surface on the first request rather than at `Builder::build()`, and `initialize` advertises capabilities from the configured sources rather than the loaded registry. Call `Builder::setLazyLoading(false)` to restore eager build-time loading.
-* Allow `[$instance, 'methodName']` as an element handler in `Builder::addTool()`, `addResource()`, `addResourceTemplate()`, and `addPrompt()`. Unblocks handlers with constructor dependencies that the container-less `new $className()` fallback cannot build.
-* Always emit an `items` schema for array tool parameters: untyped arrays get `items: {}` and nullable typed arrays (e.g. `string[]|null`) keep their element type. Fixes strict clients rejecting tools with "array type must have items" (#151).
-* Harden JSON-RPC input parsing: single-message vs batch is now decided from the decoded JSON type (object → single, list array → batch) instead of the raw first byte. Scalars, empty payloads, and non-object batch elements are surfaced as `InvalidInputMessageException` entries instead of triggering warnings or a `TypeError`.
-* Add `maxBatchSize` (default `100`) to `MessageFactory` — oversized JSON-RPC batches are rejected before any message is constructed, guarding against amplification.
-* Add `maxBodyBytes` (default 4 MiB) to `StreamableHttpTransport` — POST bodies exceeding the cap are rejected with `413`. Unknown-size/chunked bodies are read incrementally and stopped at the cap so they cannot exhaust memory.
-* Reject malformed `Mcp-Session-Id` headers with a `400` response: a repeated header or a value that is not a valid UUID is now rejected up front instead of surfacing as an uncaught `Uuid::fromString()` error.
-* Extract RFC 9728 metadata serving into `ProtectedResourceMetadataHandler`, a transport-neutral PSR-15 `RequestHandlerInterface` that can be mounted directly as a Symfony/Laravel controller; `ProtectedResourceMetadataMiddleware` now delegates to it (no BC break).
-
 0.6.0
 -----

--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -1,84 +0,0 @@
-# Contributing
-
-Thanks for considering a contribution to the PHP SDK for the Model Context Protocol. This is a
-collaboration between [the PHP Foundation](https://thephp.foundation/) and the
-[Symfony project](https://symfony.com/), and it follows Symfony's conventions throughout.
-
-## Ways to contribute
-
- **Report a bug** or **propose a feature** by [opening an issue](https://github.com/modelcontextprotocol/php-sdk/issues).
-  Check existing issues first — many spec-driven changes are already tracked under the relevant
-  `2026-07-28`-style release label.
- **Send a pull request** for a fix, a new capability, or a docs improvement.
- **Improve the guides** under `docs/` — see [Documentation](#documentation) below for how they're built.
- **Help close a conformance gap** — `make conformance-tests` runs the official MCP conformance
-  suite against this SDK; a failing scenario there is a concrete, well-scoped contribution.
-
-## Development setup
-
-Requires PHP 8.1+.
-
-```bash
-composer install
-```
-
-## Before opening a pull request
-
-Run the full CI suite locally:
-
-```bash
-make ci
-```
-
-This runs, in order: `make cs` (PHP CS Fixer, auto-fixes style), `make phpstan` (static analysis),
-and `make tests` (unit + inspector tests). All three must pass. If your change touches
-protocol-observable behavior, also run:
-
-```bash
-make conformance-tests   # requires Docker
-```
-
-## Coding standards
-
-This project follows [Symfony's coding standards](https://symfony.com/doc/current/contributing/code/standards.html)
-and [backward compatibility promise](https://symfony.com/doc/current/contributing/code/bc.html). In short:
-
-See [CLAUDE.md](CLAUDE.md) for a fuller tour of the codebase's architecture and layout.
-
-## Tests
-
-New capabilities need unit tests (`tests/Unit/`) covering the core logic, and — for anything
-reachable over the wire — inspector tests (`tests/Inspector/`) for end-to-end coverage. If you're
-adding a documented pattern, consider adding or updating an example under `examples/`.
-
-## Documentation
-
-The guides under `docs/` are built with [Zensical](https://zensical.org/) in `--strict` mode,
-which fails the build on a broken internal link:
-
-```bash
-make docs-guides
-```
-
-Links between guide pages must be relative paths that resolve within `docs/` (e.g.
-`protocol-versions.md`, `../CLAUDE.md` will *not* resolve — Zensical only follows the `docs/` tree).
-For anything at the repo root (`CLAUDE.md`, `ROADMAP.md`, `CHANGELOG.md`), link to it by its GitHub
-URL instead, matching the pattern already used across `docs/`. The class-level API reference is
-generated separately by phpDocumentor (`make docs-api`) and isn't hand-written.
-
-## Versioning
-
-The SDK follows [Semantic Versioning](https://semver.org/) — see
-[SDK tier target](docs/sdk-tier.md#versioning) for what that means pre- and post-1.0, and how it
-lines up with Symfony's backward compatibility promise.
-
-## Licensing
-
-New contributions are licensed under Apache License, Version 2.0. Existing code predating this
-policy remains under the MIT License — see [LICENSE](LICENSE) for the details. By opening a pull
-request, you agree your contribution is provided under those terms.
-
-## Getting help
-
-If something is unclear or you want early feedback on an approach before writing code, open an
-issue or a draft pull request — that's the right place to ask, rather than guessing at scope.
--- a/62
+++ b/62
@ -1,15 +1,4 @@
-.PHONY: deps-stable deps-low cs phpstan tests unit-tests integration-tests inspector-tests coverage ci ci-stable ci-lowest conformance-tests conformance-server conformance-client conformance-draft conformance-draft-server conformance-draft-client docs docs-guides docs-api docs-serve
-
-# The 2026-07-28 scenarios ship on the `alpha` dist-tag; `latest` (0.1.x) has
-# none of them. Pinned to the same version CI runs (see
-# .github/workflows/pipeline.yaml), so a local pass means a green pipeline.
-CONFORMANCE_VERSION ?= 0.2.0-alpha.11
-CONFORMANCE = npx --yes @modelcontextprotocol/conformance@$(CONFORMANCE_VERSION)
-
-# The documentation toolchain is Python (Zensical, see requirements-docs.txt),
-# run through uv so no virtualenv has to be managed by hand:
-# https://docs.astral.sh/uv/getting-started/installation/
-DOCS_RUN = uv run --no-project --with-requirements requirements-docs.txt --
+.PHONY: deps-stable deps-low cs phpstan tests unit-tests inspector-tests coverage ci ci-stable ci-lowest conformance-tests conformance-server conformance-client docs

 deps-stable:
 	composer update --prefer-stable
@ -29,9 +18,6 @@ tests:
 unit-tests:
 	vendor/bin/phpunit --testsuite=unit

-integration-tests:
-	vendor/bin/phpunit --testsuite=integration
-
 inspector-tests:
 	vendor/bin/phpunit --testsuite=inspector

@ -42,32 +28,14 @@ conformance-server:
 	@echo "Waiting for server to start..."
 	@sleep 5
 	rm -rf tests/Conformance/results
-	cd tests/Conformance && $(CONFORMANCE) server --url http://localhost:8000/ --suite all --spec-version 2025-11-25 --expected-failures conformance-baseline-2025-11-25.yml --output-dir results || true
-	php tests/Conformance/score.php server 2025-11-25
+	cd tests/Conformance && npx @modelcontextprotocol/conformance server --url http://localhost:8000/ --output-dir results || true
+	php tests/Conformance/score.php server
 	docker compose -f tests/Conformance/Fixtures/docker-compose.yml down

 conformance-client:
 	rm -rf tests/Conformance/results
-	cd tests/Conformance && $(CONFORMANCE) client --command "php $(CURDIR)/tests/Conformance/client.php" --suite all --spec-version 2025-11-25 --expected-failures conformance-baseline-2025-11-25.yml --output-dir results || true
-	php tests/Conformance/score.php client 2025-11-25
-
-# --- 2026-07-28 (SEP-2575 stateless lifecycle) ------------------------------
-
-conformance-draft: conformance-draft-server conformance-draft-client
-
-conformance-draft-server:
-	docker compose -f tests/Conformance/Fixtures/docker-compose.yml up -d
-	@echo "Waiting for server to start..."
-	@sleep 5
-	rm -rf tests/Conformance/results-2026-07-28
-	cd tests/Conformance && $(CONFORMANCE) server --url http://localhost:8000/ --suite all --spec-version 2026-07-28 --expected-failures conformance-baseline-2026-07-28.yml --output-dir results-2026-07-28 || true
-	php tests/Conformance/score.php server 2026-07-28 results-2026-07-28
-	docker compose -f tests/Conformance/Fixtures/docker-compose.yml down
-
-conformance-draft-client:
-	rm -rf tests/Conformance/results-2026-07-28
-	cd tests/Conformance && $(CONFORMANCE) client --command "php $(CURDIR)/tests/Conformance/client.php" --suite all --spec-version 2026-07-28 --expected-failures conformance-baseline-2026-07-28.yml --output-dir results-2026-07-28 || true
-	php tests/Conformance/score.php client 2026-07-28 results-2026-07-28
+	cd tests/Conformance && npx @modelcontextprotocol/conformance client --command "php $(CURDIR)/tests/Conformance/client.php" --suite all --expected-failures conformance-baseline.yml --output-dir results || true
+	php tests/Conformance/score.php client

 coverage:
 	XDEBUG_MODE=coverage vendor/bin/phpunit --testsuite=unit --coverage-html=coverage
@ -78,19 +46,7 @@ ci-stable: deps-stable cs phpstan tests

 ci-lowest: deps-low cs phpstan tests

-# The published site is the guides (Zensical) with the phpDocumentor API
-# reference mounted at /api/. `zensical build` wipes site/, so it runs first.
-docs: docs-guides docs-api
-	rm -rf site/api
-	cp -a .phpdoc/build/api site/api
-
-docs-guides:
-	$(DOCS_RUN) zensical build --strict
-
-docs-api:
-	vendor/bin/phpdoc --no-interaction
-	@grep -q 'No errors have been found' .phpdoc/build/api/reports/errors.html || \
-		(echo "Documentation errors found. See .phpdoc/build/api/reports/errors.html" && exit 1)
-
-docs-serve:
-	$(DOCS_RUN) zensical serve
+docs:
+	vendor/bin/phpdoc
+	@grep -q 'No errors have been found' .phpdoc/build/reports/errors.html || \
+		(echo "Documentation errors found. See build/docs/reports/errors.html" && exit 1)
--- a/README.md
+++ b/README.md
@ -1,13 +1,18 @@
 # MCP PHP SDK

+<div align="center">
+
 [![Latest Version](https://img.shields.io/packagist/v/mcp/sdk.svg)](https://packagist.org/packages/mcp/sdk)
 [![CI](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/pipeline.yaml/badge.svg)](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/pipeline.yaml)
 [![PHP Version](https://img.shields.io/packagist/php-v/mcp/sdk.svg)](https://packagist.org/packages/mcp/sdk)
 [![License](https://img.shields.io/packagist/l/mcp/sdk.svg)](LICENSE)
+[![Server Conformance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/modelcontextprotocol/php-sdk/badges/server-conformance.json)](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/conformance-weekly.yaml)
+[![Client Conformance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/modelcontextprotocol/php-sdk/badges/client-conformance.json)](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/conformance-weekly.yaml)

-The official PHP SDK for the Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP
-servers and clients in PHP — tools, resources, prompts, STDIO and HTTP transports, sessions, authorization, and both
-protocol eras (the `initialize` handshake and the stateless `2026-07-28` revision).
+</div>
+
+The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers
+and clients in PHP.

 This project represents a collaboration between [the PHP Foundation](https://thephp.foundation/) and the [Symfony project](https://symfony.com/). It adopts
 development practices and standards from the Symfony project, including [Coding Standards](https://symfony.com/doc/current/contributing/code/standards.html) and the
@ -16,16 +21,18 @@ development practices and standards from the Symfony project, including [Coding
 Until the first major release, this SDK is considered [experimental](https://symfony.com/doc/current/contributing/code/experimental.html), please see the [roadmap](./ROADMAP.md) for
 planned next steps and features.

-## Protocol Conformance
+## Table of Contents

-Measured weekly against the [MCP Conformance Test Framework](https://github.com/modelcontextprotocol/conformance),
-as passing checks out of total. The `2026-07-28` scores run against the framework's `alpha` releases, so they move as
-upstream publishes new scenarios.
-
-| Revision | Server | Client |
-|:--------:|:------:|:------:|
-| `2026-07-28` | [![Server conformance 2026-07-28](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/modelcontextprotocol/php-sdk/badges/server-conformance-2026-07-28.json)](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/conformance-weekly.yaml) | [![Client conformance 2026-07-28](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/modelcontextprotocol/php-sdk/badges/client-conformance-2026-07-28.json)](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/conformance-weekly.yaml) |
-| `2025-11-25` | [![Server conformance 2025-11-25](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/modelcontextprotocol/php-sdk/badges/server-conformance-2025-11-25.json)](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/conformance-weekly.yaml) | [![Client conformance 2025-11-25](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/modelcontextprotocol/php-sdk/badges/client-conformance-2025-11-25.json)](https://github.com/modelcontextprotocol/php-sdk/actions/workflows/conformance-weekly.yaml) |
+- [Installation](#installation)
+- [Overview](#overview)
+- [Server SDK](#server-sdk)
+- [Client SDK](#client-sdk)
+- [Documentation](#documentation)
+- [External Resources](#external-resources)
+- [PHP Libraries Using the MCP SDK](#php-libraries-using-the-mcp-sdk)
+- [Contributing](#contributing)
+- [Credits](#credits)
+- [License](#license)

 ## Installation

@ -33,21 +40,28 @@ upstream publishes new scenarios.
 composer require mcp/sdk
 ```

-## Build a server
+## Overview

-A server is a plain PHP class plus three lines of wiring:
+The MCP PHP SDK provides both **server** and **client** implementations for the Model Context Protocol, enabling you to:
+
+- **Build MCP Servers**: Expose your PHP application's functionality (tools, resources, prompts) to AI agents
+- **Build MCP Clients**: Connect to and interact with MCP servers from your PHP applications
+
+## Server SDK
+
+Build MCP servers to expose your PHP application's capabilities to AI agents like Claude, Codex, and others.
+
+### Quick Start

 ```php
-use Mcp\Capability\Attribute\McpResource;
-use Mcp\Capability\Attribute\McpTool;
 use Mcp\Server;
 use Mcp\Server\Transport\StdioTransport;
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Capability\Attribute\McpResource;

-class Calculator
+// Define capabilities using PHP attributes
+class CalculatorCapabilities
 {
-    /**
-     * Adds two numbers.
-     */
    #[McpTool]
    public function add(int $a, int $b): int
    {
@ -55,56 +69,218 @@ class Calculator
    }

    #[McpResource(uri: 'config://calculator/settings')]
-    public function settings(): array
+    public function getSettings(): array
    {
        return ['precision' => 2];
    }
 }

-exit(Server::builder()
-    ->setServerInfo('Calculator', '1.0.0')
-    ->setDiscovery(__DIR__, ['.'], excludeDirs: ['vendor'])
-    ->build()
-    ->run(new StdioTransport()));
+// Build and run the server
+$server = Server::builder()
+    ->setServerInfo('Calculator Server', '1.0.0')
+    ->setDiscovery(__DIR__, ['.'])  // Auto-discover attributes
+    ->build();
+
+$transport = new StdioTransport();
+$server->run($transport);
 ```

-The walkthrough in [First server](docs/get-started/first-server.md) explains each piece, and
-[Try it with the Inspector](docs/get-started/inspector.md) shows it running.
+### Server Capabilities

-## Build a client
+- **Tools**: Executable functions that AI agents can call
+- **Resources**: Data sources that can be read (files, configs, databases)
+- **Resource Templates**: Dynamic resources with URI parameters
+- **Prompts**: Pre-defined templates for AI interactions
+- **Server-Initiated Communication**: Elicitations, sampling, logging, progress notifications
+
+### Registration Methods
+
+There are multiple ways to register your MCP capabilities—choose the approach that best fits your application's architecture:
+
+**1. Attribute-Based Discovery** — Define capabilities using PHP attributes for automatic discovery:
+```php
+#[McpTool]
+public function generateReport(): string { /* ... */ }
+
+#[McpResource(uri: 'config://app/settings')]
+public function getConfig(): array { /* ... */ }
+```
+
+**2. Manual Registration** — Register capabilities programmatically without attributes:
+```php
+$server = Server::builder()
+    ->addTool([Calculator::class, 'add'], 'add_numbers')
+    ->addResource([Config::class, 'get'], 'config://app')
+    ->build();
+```
+
+**3. Hybrid Approach** — Combine both methods for maximum flexibility:
+```php
+$server = Server::builder()
+    ->setDiscovery(__DIR__, ['.'])
+    ->addTool([ExternalService::class, 'process'], 'external')
+    ->build();
+```
+
+### Transports
+
+Choose the transport that matches your deployment environment:
+
+**1. STDIO Transport** — For command-line integration and local processes:
+```php
+$transport = new StdioTransport();
+$server->run($transport);
+```
+
+**2. HTTP Transport** — For web-based servers and distributed systems:
+```php
+$transport = new StreamableHttpTransport($request, $responseFactory, $streamFactory);
+$response = $server->run($transport);
+```
+
+### Session Management
+
+Configure session storage to maintain state between requests. Choose the backend that fits your infrastructure:
+
+**In-Memory** (default, suitable for STDIO):
+```php
+$server = Server::builder()
+    ->setSession(ttl: 7200) // 2 hours
+    ->build();
+```
+
+**File-Based** (suitable for single-server HTTP deployments):
+```php
+$server = Server::builder()
+    ->setSession(new FileSessionStore(__DIR__ . '/sessions'))
+    ->build();
+```
+
+**PSR-16 Cache** (for example with Redis for scaled deployments):
+```php
+$server = Server::builder()
+    ->setSession(new Psr16SessionStore(
+        cache: new Psr16Cache($redisAdapter),
+        prefix: 'mcp-',
+        ttl: 3600
+    ))
+    ->build();
+```
+
+[→ Server Documentation](docs/server-builder.md)
+
+## Client SDK
+
+Connect to MCP servers from your PHP applications to access their tools, resources, and prompts.
+
+### Quick Start

 ```php
 use Mcp\Client;
 use Mcp\Client\Transport\StdioTransport;

+// Build the client
 $client = Client::builder()
    ->setClientInfo('My Application', '1.0.0')
+    ->setInitTimeout(30)
+    ->setRequestTimeout(120)
    ->build();

-$client->connect(new StdioTransport(command: 'php', args: ['/path/to/server.php']));
+// Connect to a server
+$transport = new StdioTransport(
+    command: 'php',
+    args: ['/path/to/server.php'],
+);

+$client->connect($transport);
+
+// Discover and use capabilities
 $tools = $client->listTools();
 $result = $client->callTool('add', ['a' => 5, 'b' => 3]);

+$resources = $client->listResources();
+$content = $client->readResource('config://calculator/settings');
+
 $client->disconnect();
 ```

-See [Connecting to a server](docs/client/connecting.md) for transports, timeouts, and the
-handlers that answer server-initiated requests.
+### Client Capabilities
+
+- **Tool Calling**: List and execute tools from any MCP server
+- **Resource Access**: Read static and dynamic resources
+- **Prompt Management**: List and retrieve prompt templates
+- **Completion Support**: Request argument completion suggestions
+
+### Advanced Features
+
+- **Progress Tracking**: Real-time progress during long operations
+```php
+$result = $client->callTool(
+    name: 'process_data',
+    arguments: ['dataset' => 'large_file.csv'],
+    onProgress: function (float $progress, ?float $total, ?string $message) {
+        echo "Progress: {$progress}/{$total} - {$message}\n";
+    }
+);
+```
+
+- **Sampling Support**: Handle server LLM sampling requests
+```php
+$samplingHandler = new SamplingRequestHandler($myCallback);
+$client = Client::builder()
+    ->setCapabilities(new ClientCapabilities(sampling: true))
+    ->addRequestHandler($samplingHandler)
+    ->build();
+```
+
+- **Logging Notifications**: Receive server log messages
+```php
+$loggingHandler = new LoggingNotificationHandler($myCallback);
+$client = Client::builder()
+    ->addNotificationHandler($loggingHandler)
+    ->build();
+```
+
+### Transports
+
+Connect to MCP servers using the transport that matches your setup:
+
+**1. STDIO Transport** — Connect to local server processes:
+```php
+$transport = new StdioTransport(
+    command: 'php',
+    args: ['/path/to/server.php'],
+);
+
+$client->connect($transport);
+```
+
+**2. HTTP Transport** — Connect to remote or web-based servers:
+```php
+$transport = new HttpTransport('http://localhost:8000');
+
+$client->connect($transport);
+```
+
+[→ Client Documentation](docs/client.md)

 ## Documentation

-The full documentation is published at **[php.sdk.modelcontextprotocol.io](https://php.sdk.modelcontextprotocol.io/)**.
+### Core Concepts

- **[Get started](docs/get-started/index.md)** — Install the SDK and build your first server
- **[Servers](docs/servers/index.md)** — Tools, resources, resource templates, prompts, and how to register them
- **[Inside your handler](docs/handlers/index.md)** — Talking back to the client, logging, and asking for input
- **[Running your server](docs/run/index.md)** — Server builder, STDIO and HTTP transports, framework integration, sessions, authorization
- **[Clients](docs/client/index.md)** — Client SDK for connecting to and communicating with MCP servers
- **[Protocol versions](docs/protocol-versions.md)** — The two protocol eras, and what revision `2026-07-28` changed
- **[Advanced](docs/advanced/index.md)** — Events, protocol extensions (including MCP Apps), and custom message handlers
- **[Examples](docs/examples.md)** — Runnable server and client examples
- **[API Reference](https://php.sdk.modelcontextprotocol.io/api/)** — Generated class reference
+- **[Server Builder](docs/server-builder.md)** — Complete ServerBuilder reference and configuration
+- **[Client](docs/client.md)** — Client SDK for connecting to and communicating with MCP servers
+- **[Transports](docs/transports.md)** — STDIO and HTTP transport setup and usage
+- **[MCP Elements](docs/mcp-elements.md)** — Creating tools, resources, prompts, and templates
+- **[Server-Client Communication](docs/server-client-communication.md)** — Sampling, logging, progress, and notifications
+- **[Protocol Extensions](docs/extensions.md)** — Opt-in protocol extensions announced during capability negotiation, including MCP Apps (HTML UI resources)
+- **[Authorization](docs/authorization.md)** — OAuth and authorization setup for HTTP transport
+- **[Events](docs/events.md)** — Hooking into server lifecycle with events
+
+### Learning & Examples
+
+- **[Examples](docs/examples.md)** — Comprehensive example walkthroughs for servers and clients
+- **[ROADMAP.md](ROADMAP.md)** — Planned features and development roadmap

 ## External Resources

@ -126,11 +302,9 @@ Building something on top of the SDK? Open a pull request to add it to this list

 ## Contributing

-We are passionate about supporting contributors of all levels of experience and would love to see you get involved in
-the project. Start by [reporting issues](https://github.com/modelcontextprotocol/php-sdk/issues) or
-[sending pull requests](https://github.com/modelcontextprotocol/php-sdk/pulls). See
-[CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and what to run before
-opening a PR.
+We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project.
+
+See the [Contributing Guide](CONTRIBUTING.md) to get started before you [report issues](https://github.com/modelcontextprotocol/php-sdk/issues) and [send pull requests](https://github.com/modelcontextprotocol/php-sdk/pulls).

 ## Credits

--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -5,17 +5,11 @@ This roadmap is a living document that outlines the planned features and improve
 ## Goals for the First Major Release

 - **Server**
- [x] Implement full support for elicitations
+- [ ] Implement full support for elicitations
 - [ ] Implement OAuth2 authentication for server
 - **Client**
 - [x] Implement client-side support
 - [x] Implement client examples and documentation
- [ ] Implement OAuth2 authentication for client
 - **Schema**
 - [ ] Implement schema generation based on TS or JSON Schema
- [ ] Achieve full spec conformance
- **Extensions**
- [ ] Implement the Tasks extension
- **Architecture**
- [ ] Split the SDK into multiple packages

--- a/adr/0001-oauth-authorization-server-out-of-scope.md
+++ b/adr/0001-oauth-authorization-server-out-of-scope.md
@ -1,97 +0,0 @@
-# 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.
--- a/adr/README.md
+++ b/adr/README.md
@ -1,10 +0,0 @@
-# Architecture Decision Records
-
-This directory holds Architecture Decision Records (ADRs): short documents that capture a
-significant architectural decision, the context that led to it, and its consequences. They
-exist so a decision can be cited once and referenced thereafter — for example, when declining
-a pull request that conflicts with an accepted decision.
-
-## Records
-
- [0001 — The MCP server is an OAuth Resource Server, not an Authorization Server](0001-oauth-authorization-server-out-of-scope.md)
--- a/composer.json
+++ b/composer.json
@ -32,7 +32,6 @@
    "psr/http-server-handler": "^1.0",
    "psr/http-server-middleware": "^1.0",
    "psr/log": "^1.0 || ^2.0 || ^3.0",
-    "symfony/deprecation-contracts": "^2.5 || ^3.0",
    "symfony/uid": "^5.4 || ^6.4 || ^7.3 || ^8.0"
  },
  "suggest": {
--- a/docs/.overrides/.icons/mcp.svg
+++ b/docs/.overrides/.icons/mcp.svg
@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180"><path fill="none" d="M23.5996 85.2532L86.2021 22.6507C94.8457 14.0071 108.86 14.0071 117.503 22.6507C126.147 31.2942 126.147 45.3083 117.503 53.9519L70.2254 101.23" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/><path fill="none" d="M70.8789 100.578L117.504 53.952C126.148 45.3083 140.163 45.3083 148.806 53.952L149.132 54.278C157.776 62.9216 157.776 76.9357 149.132 85.5792L92.5139 142.198C89.6327 145.079 89.6327 149.75 92.5139 152.631L104.14 164.257" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/><path fill="none" d="M101.853 38.3013L55.553 84.6011C46.9094 93.2447 46.9094 107.258 55.553 115.902C64.1966 124.546 78.2106 124.546 86.8543 115.902L133.154 69.6025" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/></svg>
--- a/docs/CNAME
+++ b/docs/CNAME
@ -1 +0,0 @@
-php.sdk.modelcontextprotocol.io
--- a/docs/advanced/custom-handlers.md
+++ b/docs/advanced/custom-handlers.md
@ -1,98 +0,0 @@
-# Custom Message Handlers
-
-**Low-level escape hatch.** Custom message handlers run before the SDK's built-in handlers and give you total control over
-individual JSON-RPC messages. They do not receive the builder's registry, container, or discovery output unless you pass
-those dependencies in yourself.
-
-> **Warning**: Custom message handlers bypass discovery, manual capability registration, and container lookups (unless
-> you explicitly pass them). Tools, resources, and prompts you register elsewhere will not show up unless your handler
-> loads and executes them manually. Reach for this API only when you need that level of control and are comfortable
-> taking on the additional plumbing.
-
-## Request Handlers
-
-Handle JSON-RPC requests (messages with an `id` that expect a response). Request handlers **must** return either a
-`Response` or an `Error` object.
-
-Attach request handlers with `addRequestHandler()` (single) or `addRequestHandlers()` (multiple). You can call these
-methods as many times as needed; handlers are collected in call order, and the whole custom list runs before the
-built-in defaults:
-
-```php
-$server = Server::builder()
-    ->addRequestHandler(new CustomListToolsHandler())
-    ->addRequestHandlers([
-        new CustomCallToolHandler(),
-        new CustomGetPromptHandler(),
-    ])
-    ->build();
-```
-
-Request handlers implement `RequestHandlerInterface`:
-
-```php
-use Mcp\Schema\JsonRpc\Error;
-use Mcp\Schema\JsonRpc\Request;
-use Mcp\Schema\JsonRpc\Response;
-use Mcp\Server\Handler\Request\RequestHandlerInterface;
-use Mcp\Server\Session\SessionInterface;
-
-interface RequestHandlerInterface
-{
-    public function supports(Request $request): bool;
-
-    public function handle(Request $request, SessionInterface $session): Response|Error;
-}
-```
-
- `supports()` decides if the handler should process the incoming request
- `handle()` **must** return a `Response` (on success) or an `Error` (on failure)
-
-## Notification Handlers
-
-Handle JSON-RPC notifications (messages without an `id` that don't expect a response). Notification handlers **do not**
-return anything - they perform side effects only.
-
-Attach notification handlers with `addNotificationHandler()` (single) or `addNotificationHandlers()` (multiple):
-
-```php
-// Handlers are your own classes implementing NotificationHandlerInterface;
-// the SDK ships only its internal ones.
-$server = Server::builder()
-    ->addNotificationHandler(new AuditNotificationHandler($auditLog))
-    ->addNotificationHandlers([
-        new MetricsNotificationHandler($metrics),
-        new CancellationNotificationHandler(),
-    ])
-    ->build();
-```
-
-Notification handlers implement `NotificationHandlerInterface`:
-
-```php
-use Mcp\Schema\JsonRpc\Notification;
-use Mcp\Server\Handler\Notification\NotificationHandlerInterface;
-use Mcp\Server\Session\SessionInterface;
-
-interface NotificationHandlerInterface
-{
-    public function supports(Notification $notification): bool;
-
-    public function handle(Notification $notification, SessionInterface $session): void;
-}
-```
-
- `supports()` decides if the handler should process the incoming notification
- `handle()` performs side effects but **does not** return a value (notifications have no response)
-
-## Key Differences
-
-| Handler Type | Interface | Returns | Use Case |
-|-------------|-----------|---------|----------|
-| Request Handler | `RequestHandlerInterface` | `Response\|Error` | Handle requests that need responses (e.g., `tools/list`, `tools/call`) |
-| Notification Handler | `NotificationHandlerInterface` | `void` | Handle fire-and-forget notifications (e.g., `notifications/initialized`, `notifications/progress`) |
-
-## Example
-
-Check out [`examples/server/custom-method-handlers/server.php`](https://github.com/modelcontextprotocol/php-sdk/blob/main/examples/server/custom-method-handlers/server.php) for a complete example showing how to implement
-custom `tools/list` and `tools/call` request handlers independently of the registry.
--- a/docs/advanced/index.md
+++ b/docs/advanced/index.md
@ -1,10 +0,0 @@
-# Advanced
-
-Everything here is optional. A working server needs none of it.
-
-* **[Events](events.md)** — PSR-14 events dispatched around every request, response,
-  error, and notification. Useful for metrics, audit logs, and debugging.
-* **[Protocol extensions](extensions.md)** — opt-in extensions announced during
-  capability negotiation, including MCP Apps (HTML UI resources).
-* **[Custom message handlers](custom-handlers.md)** — taking over a JSON-RPC method the
-  SDK does not implement, or overriding one it does.
--- a/docs/authorization.md
+++ b/docs/authorization.md
@ -0,0 +1,430 @@
+# Authorization
+
+The PHP MCP SDK provides OAuth 2.1 authorization support for HTTP transports, implementing the
+[MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start](#quick-start)
+- [Components](#components)
+- [JWT Token Validation](#jwt-token-validation)
+- [Protected Resource Metadata](#protected-resource-metadata)
+- [Custom Token Validators](#custom-token-validators)
+- [Scope-Based Access Control](#scope-based-access-control)
+- [Examples](#examples)
+
+## Overview
+
+Authorization in MCP is implemented at the transport level using PSR-15 middleware. The SDK provides:
+
+- **AuthorizationMiddleware** - PSR-15 middleware that enforces bearer token authentication
+- **ProtectedResourceMetadataMiddleware** - Serves RFC 9728 metadata at well-known endpoints
+- **OAuthProxyMiddleware** - Proxies OAuth flows to upstream authorization servers
+- **OAuthRequestMetaMiddleware** - Bridges HTTP OAuth attributes to JSON-RPC request meta
+- **JwtTokenValidator** - Validates JWT tokens using JWKS from OAuth 2.0 / OIDC providers
+- **OidcDiscovery** - Discovers authorization server metadata from well-known endpoints
+
+```
+┌─────────────┐     ┌────────────────────┐     ┌─────────────────┐
+│ MCP Client  │────▶│ AuthorizationMiddleware │────▶│  MCP Handlers   │
+└─────────────┘     └────────────────────┘     └─────────────────┘
+      │                      │
+      │                      │ Validate JWT
+      ▼                      ▼
+┌─────────────┐     ┌─────────────────┐
+│ Auth Server │◀────│ JwtTokenValidator│
+│  (Keycloak, │     │    + JWKS       │
+│   Entra ID) │     └─────────────────┘
+└─────────────┘
+```
+
+## Quick Start
+
+```php
+use Mcp\Server;
+use Mcp\Server\Transport\Http\Middleware\AuthorizationMiddleware;
+use Mcp\Server\Transport\Http\Middleware\ProtectedResourceMetadataMiddleware;
+use Mcp\Server\Transport\Http\OAuth\JwksProvider;
+use Mcp\Server\Transport\Http\OAuth\JwtTokenValidator;
+use Mcp\Server\Transport\Http\OAuth\OidcDiscovery;
+use Mcp\Server\Transport\Http\OAuth\ProtectedResourceMetadata;
+use Mcp\Server\Transport\StreamableHttpTransport;
+
+// 1. Set up OIDC discovery and JWKS provider
+$discovery = new OidcDiscovery();
+$jwksProvider = new JwksProvider($discovery);
+
+// 2. Create JWT validator for your OAuth provider
+$validator = new JwtTokenValidator(
+    issuer: 'https://auth.example.com/realms/mcp',
+    audience: 'mcp-server',
+    jwksProvider: $jwksProvider,
+);
+
+// 3. Create Protected Resource Metadata (RFC 9728)
+$metadata = new ProtectedResourceMetadata(
+    authorizationServers: ['https://auth.example.com/realms/mcp'],
+    scopesSupported: ['mcp:read', 'mcp:write'],
+);
+
+// 4. Create middleware stack
+$authMiddleware = new AuthorizationMiddleware(
+    validator: $validator,
+    resourceMetadata: $metadata,
+);
+
+$metadataMiddleware = new ProtectedResourceMetadataMiddleware(
+    metadata: $metadata,
+);
+
+// 5. Create transport with middleware
+$transport = new StreamableHttpTransport(
+    $request,
+    middlewares: [$metadataMiddleware, $authMiddleware],
+);
+
+// 6. Run server
+$server = Server::builder()
+    ->setServerInfo('Protected MCP Server', '1.0.0')
+    ->setDiscovery(__DIR__)
+    ->build();
+
+$response = $server->run($transport);
+```
+
+## Components
+
+### AuthorizationMiddleware
+
+The main middleware that enforces authentication:
+
+```php
+$middleware = new AuthorizationMiddleware(
+    validator: $validator,         // AuthorizationTokenValidatorInterface
+    resourceMetadata: $metadata,   // ProtectedResourceMetadata instance
+    responseFactory: null,         // PSR-17 (auto-discovered)
+);
+```
+
+**Behavior:**
+
+| Request | Response |
+|---------|----------|
+| Missing Authorization header | 401 with `WWW-Authenticate: Bearer resource_metadata="..."` |
+| Invalid/expired token | 401 with error details |
+| Valid token | Passes to next handler with OAuth attributes on request |
+
+### ProtectedResourceMetadataMiddleware
+
+Serves Protected Resource Metadata at configured well-known paths:
+
+```php
+$metadataMiddleware = new ProtectedResourceMetadataMiddleware(
+    metadata: $metadata,           // ProtectedResourceMetadata instance
+    responseFactory: null,         // PSR-17 (auto-discovered)
+    streamFactory: null,           // PSR-17 (auto-discovered)
+);
+```
+
+### JwtTokenValidator
+
+Validates JWT access tokens:
+
+```php
+$validator = new JwtTokenValidator(
+    issuer: 'https://auth.example.com',  // Expected issuer claim
+    audience: 'mcp-server',              // Expected audience (string or array)
+    jwksProvider: $jwksProvider,          // JwksProviderInterface
+    jwksUri: null,                       // Explicit JWKS URI (auto-discovered)
+    algorithms: ['RS256', 'RS384'],      // Allowed algorithms
+    scopeClaim: 'scope',                 // Claim name for scopes
+);
+```
+
+**Request Attributes:**
+
+After successful validation, these attributes are added to the request:
+
+| Attribute | Description |
+|-----------|-------------|
+| `oauth.claims` | All JWT claims as array |
+| `oauth.scopes` | Extracted scopes as array |
+| `oauth.subject` | The `sub` claim |
+| `oauth.client_id` | The `client_id` claim (if present) |
+| `oauth.authorized_party` | The `azp` claim (if present) |
+
+### ProtectedResourceMetadata
+
+Represents RFC 9728 Protected Resource Metadata:
+
+```php
+$metadata = new ProtectedResourceMetadata(
+    authorizationServers: [              // Required: authorization server URLs
+        'https://auth.example.com',
+    ],
+    scopesSupported: [                   // Optional: supported scopes
+        'mcp:read',
+        'mcp:write',
+    ],
+    resource: 'https://mcp.example.com', // Optional: resource identifier
+    resourceName: 'My MCP Server',       // Optional: human-readable name
+    metadataPaths: [                     // Paths to serve metadata (default: /.well-known/oauth-protected-resource)
+        '/.well-known/oauth-protected-resource',
+    ],
+    extra: [                             // Optional: additional fields
+        'custom_field' => 'value',
+    ],
+);
+```
+
+### OidcDiscovery
+
+Discovers OAuth/OIDC server metadata:
+
+```php
+$discovery = new OidcDiscovery(
+    httpClient: null,      // PSR-18 (auto-discovered)
+    requestFactory: null,  // PSR-17 (auto-discovered)
+    cache: $cache,         // PSR-16 cache (optional)
+    cacheTtl: 3600,        // Cache TTL
+);
+
+// Discover metadata
+$metadata = $discovery->discover('https://auth.example.com/realms/mcp');
+
+// Get specific endpoints
+$jwksUri = $discovery->getJwksUri($issuer);
+$tokenEndpoint = $discovery->getTokenEndpoint($issuer);
+$authEndpoint = $discovery->getAuthorizationEndpoint($issuer);
+```
+
+### JwksProvider
+
+Fetches and caches JWKS key sets:
+
+```php
+$jwksProvider = new JwksProvider(
+    discovery: $discovery,     // OidcDiscoveryInterface
+    httpClient: null,          // PSR-18 (auto-discovered)
+    requestFactory: null,      // PSR-17 (auto-discovered)
+    cache: $cache,             // PSR-16 cache (optional)
+    cacheTtl: 3600,            // JWKS cache TTL
+);
+```
+
+## JWT Token Validation
+
+### Keycloak
+
+```php
+$validator = new JwtTokenValidator(
+    issuer: 'https://keycloak.example.com/realms/mcp',
+    audience: 'mcp-server',
+    jwksProvider: $jwksProvider,
+);
+```
+
+### Microsoft Entra ID (Azure AD)
+
+```php
+$tenantId = 'your-tenant-id';
+$clientId = 'your-client-id';
+
+$validator = new JwtTokenValidator(
+    issuer: "https://login.microsoftonline.com/{$tenantId}/v2.0",
+    audience: $clientId,
+    jwksProvider: $jwksProvider,
+);
+```
+
+### Auth0
+
+```php
+$validator = new JwtTokenValidator(
+    issuer: 'https://your-tenant.auth0.com/',
+    audience: 'https://api.example.com',
+    jwksProvider: $jwksProvider,
+);
+```
+
+### Okta
+
+```php
+$validator = new JwtTokenValidator(
+    issuer: 'https://your-org.okta.com/oauth2/default',
+    audience: 'api://default',
+    jwksProvider: $jwksProvider,
+);
+```
+
+## Protected Resource Metadata
+
+The `ProtectedResourceMetadataMiddleware` serves Protected Resource Metadata at configured paths, enabling clients to discover the authorization server:
+
+```json
+{
+  "authorization_servers": ["https://auth.example.com/realms/mcp"],
+  "scopes_supported": ["mcp:read", "mcp:write"],
+  "resource": "https://mcp.example.com/mcp"
+}
+```
+
+Clients request this from `/.well-known/oauth-protected-resource` before authenticating.
+
+### WWW-Authenticate Header
+
+On 401 responses, the middleware includes:
+
+```
+WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
+                         scope="mcp:read mcp:write"
+```
+
+## Custom Token Validators
+
+Implement `AuthorizationTokenValidatorInterface` for custom validation:
+
+```php
+use Mcp\Server\Transport\Http\OAuth\AuthorizationTokenValidatorInterface;
+use Mcp\Server\Transport\Http\OAuth\AuthorizationResult;
+
+final class ApiKeyValidator implements AuthorizationTokenValidatorInterface
+{
+    public function __construct(
+        private array $validKeys,
+    ) {}
+
+    public function validate(string $accessToken): AuthorizationResult
+    {
+        if (!isset($this->validKeys[$accessToken])) {
+            return AuthorizationResult::unauthorized(
+                'invalid_token',
+                'Unknown API key'
+            );
+        }
+
+        $keyInfo = $this->validKeys[$accessToken];
+
+        return AuthorizationResult::allow([
+            'api_key.name' => $keyInfo['name'],
+            'api_key.scopes' => $keyInfo['scopes'],
+        ]);
+    }
+}
+
+// Usage
+$validator = new ApiKeyValidator([
+    'sk_live_abc123' => ['name' => 'Production', 'scopes' => ['read', 'write']],
+]);
+```
+
+### AuthorizationResult
+
+Factory methods for different outcomes:
+
+```php
+// Allow access with attributes
+AuthorizationResult::allow(['user_id' => '123']);
+
+// Deny - missing/invalid token (401)
+AuthorizationResult::unauthorized('invalid_token', 'Token expired');
+
+// Deny - valid token but insufficient permissions (403)
+AuthorizationResult::forbidden('insufficient_scope', 'Requires admin scope', ['admin']);
+
+// Deny - malformed request (400)
+AuthorizationResult::badRequest('invalid_request', 'Malformed header');
+```
+
+## Scope-Based Access Control
+
+### Checking Scopes in Handlers
+
+```php
+#[McpTool(name: 'admin_action')]
+public function adminAction(RequestContext $context): array
+{
+    $scopes = $context->getRequest()?->getAttribute('oauth.scopes') ?? [];
+
+    if (!in_array('mcp:admin', $scopes, true)) {
+        throw new \RuntimeException('Admin scope required');
+    }
+
+    // Perform admin action
+    return ['status' => 'success'];
+}
+```
+
+### Using JwtTokenValidator::requireScopes
+
+```php
+// In a custom middleware or handler
+$result = $validator->validate($token);
+
+if ($result->isAllowed()) {
+    // Check for specific scopes
+    $result = $validator->requireScopes($result, ['mcp:write']);
+}
+
+if (!$result->isAllowed()) {
+    // Handle insufficient scope (returns 403)
+}
+```
+
+## Examples
+
+Complete working examples are available in the `examples/server/` directory:
+
+### Keycloak Example
+
+```bash
+cd examples/server/oauth-keycloak
+docker-compose up -d
+
+# Test credentials: demo / demo123
+```
+
+See [oauth-keycloak/README.md](../examples/server/oauth-keycloak/README.md)
+
+### Microsoft Entra ID Example
+
+```bash
+cd examples/server/oauth-microsoft
+cp env.example .env
+# Edit .env with your Azure credentials
+docker-compose up -d
+```
+
+See [oauth-microsoft/README.md](../examples/server/oauth-microsoft/README.md)
+
+## Security Considerations
+
+1. **Always use HTTPS** in production for token transmission
+2. **Validate audience claims** to prevent token confusion attacks
+3. **Use short-lived tokens** and implement token refresh
+4. **Cache JWKS** to reduce latency but allow for key rotation
+5. **Never log tokens** - log only non-sensitive claims like subject
+6. **Validate scopes** before performing sensitive operations
+
+## Troubleshooting
+
+### "Invalid issuer" error
+
+The `iss` claim in the token must exactly match the configured issuer URL, including trailing slashes.
+
+### "Invalid audience" error
+
+Check the `aud` claim matches your configured audience. Some providers use the client ID, others use a custom URI.
+
+### JWKS fetch timeout
+
+- Ensure network connectivity to the authorization server
+- Consider using a cache to reduce dependency on the auth server
+- Check firewall rules allow outbound HTTPS
+
+### Token expired
+
+- Check clock synchronization between servers
+- Tokens typically have a 5-minute clock skew tolerance
+- Ensure clients refresh tokens before expiration
--- a/Show more
+++ b/Show more
				`@ -1 +0,0 @@`
				<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 180"><path fill="none" d="M23.5996 85.2532L86.2021 22.6507C94.8457 14.0071 108.86 14.0071 117.503 22.6507C126.147 31.2942 126.147 45.3083 117.503 53.9519L70.2254 101.23" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/><path fill="none" d="M70.8789 100.578L117.504 53.952C126.148 45.3083 140.163 45.3083 148.806 53.952L149.132 54.278C157.776 62.9216 157.776 76.9357 149.132 85.5792L92.5139 142.198C89.6327 145.079 89.6327 149.75 92.5139 152.631L104.14 164.257" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/><path fill="none" d="M101.853 38.3013L55.553 84.6011C46.9094 93.2447 46.9094 107.258 55.553 115.902C64.1966 124.546 78.2106 124.546 86.8543 115.902L133.154 69.6025" stroke="currentColor" stroke-width="11.0667" stroke-linecap="round"/></svg>