Skip to content

docs: add section about software_statement to Authorization page#883

Closed
knguyen-figma wants to merge 6 commits into
modelcontextprotocol:mainfrom
knguyen-figma:feature/dcr-software-statement
Closed

docs: add section about software_statement to Authorization page#883
knguyen-figma wants to merge 6 commits into
modelcontextprotocol:mainfrom
knguyen-figma:feature/dcr-software-statement

Conversation

@knguyen-figma

@knguyen-figma knguyen-figma commented Jul 1, 2025

Copy link
Copy Markdown

Motivation and Context

Problem

The current MCP Dynamic Client Registration (DCR) flow lacks a way to verify the authenticity of client software attempting to register. This creates several challenges for authorization servers:

  1. Cannot distinguish between legitimate MCP clients and potentially malicious implementations
  2. No cryptographic way to verify that a client was created by a trusted vendor
  3. Limited ability to audit which vendors' clients are using the system
  4. Difficult to implement vendor-specific policies (rate limits, feature flags, allowlisting, blocking, etc.)

Proposal

Recommend that MCP clients send software_statement and jwks_uri fields in DCR requests, as defined in RFC 7591. This enables:

  • Clients to provide cryptographically signed statements about their identity (they are who they say they are)
  • Authorization servers to verify client authenticity using vendor public keys
    • Authorization servers can maintain their own list of trusted jwks_uris or have some self-service mechanism for clients (outside the scope of the MCP spec)
  • Consistent client identification across registrations so that authorization servers can collate/group client registration to a certain vendors or software. This makes it easier to manage vendor-specific policies.
sequenceDiagram
    participant C as MCP Client
    participant CB as Software Vendor Server
    participant A as Authorization Server

    Note over C,CB: Software Statement Preparation
    C->>CB: Request software_statement JWT
    Note over CB: Generate JWT with claims:<br/>- client metadata<br/>- software ID<br/>- software version<br/>- expiration
    CB-->>C: Signed software_statement JWT

    Note over C,A: Dynamic Registration
    C->>A: POST /register<br/>software_statement + jwks_uri
    A->>CB: GET /mcp/jwks.json
    CB-->>A: JWKS document
    Note over A: 1. Validate software_statement<br/>2. Verify JWT signature using JWKS<br/>3. Check issuer trust<br/>4. Validate claims & expiry
    A-->>C: Client credentials
Loading

How Has This Been Tested?

Here's a simple MCP server (no tools, just auth) that supports software_statement and jwks_uri: https://github.com/knguyen-figma/mcp-auth-server-software-statement

I tested it by updating @modelcontextprotocol/inspector to sign the JWT with a private key via a protected endpoint in the proxy server and to host the JWKS. knguyen-figma/inspector@f12f5c0

Breaking Changes

No breaking changes. While the change is recommending that MCP clients send software_statement and jwks_uri during DCR, it is not required.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • [ x] Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context


@localden localden left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Support the idea of adding software statements. Suggesting trimming the content a bit to make sure we're not replicating the DCR RFC.

Comment thread docs/specification/draft/basic/authorization.mdx Outdated
Comment thread docs/specification/draft/basic/authorization.mdx Outdated
Comment thread docs/specification/draft/basic/authorization.mdx Outdated
@knguyen-figma
knguyen-figma requested a review from localden July 9, 2025 01:07
@knguyen-figma
knguyen-figma force-pushed the feature/dcr-software-statement branch from 3cb20e7 to e064b84 Compare July 10, 2025 15:26
@aaronpk

aaronpk commented Jul 23, 2025

Copy link
Copy Markdown
Contributor

This needs a way to prevent the software statement from being replayed at another AS.

The software statement needs to include a claim with the authorization server issuer.

Without this, a client will be generating the same looking software statement and sending it to different AS's, so a malicious AS could replay it at a legitimate AS.

@nynymike

Copy link
Copy Markdown

Good approach. BTW, Jans Auth Server can mint SSA's and key rotation for the SSA signing key has a less frequent rotation period versus other OAuth JWTs: See docs: https://docs.jans.io/stable/janssen-server/auth-server/endpoints/ssa/

@dsp-ant

dsp-ant commented Nov 24, 2025

Copy link
Copy Markdown
Member

I am closing this since there was little to no action in months. If you think this is still valuable, please open a SEP or a PR, depending on the change. See https://modelcontextprotocol.io/community/sep-guidelines

@dsp-ant dsp-ant closed this Nov 24, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants