Skip to content

Add authorization examples in documentation #1315

Open

Description

@Kehrlann

Our documentation lacks guidance and examples around authorization.

We should explain at a high-level, with code examples:

  • how to make authentication obtained outside the SDK available to the server handlers, repositories, and filters
  • how to use the client-side hooks to plug the client into an existing OAuth2 framework

In the case of the modern client, clarify the relationship between a "client" and a "user".

Initially reported in #1313

Activity

  1. media-ctrl commented on Nov 9, 2026

    @media-ctrl
  2. mohit32886 commented on Nov 16, 2026

    @mohit32886

    Hi @Kehrlann, I went through the current docs on main after #1329 landed to see what is already covered and what is still missing.

    docs/client-modern.md already has a solid "Identity and Authorization" section covering HttpClientMcpTransport, requestCustomizer, authorizationErrorHandler, and why transports should be shared across users rather than client instances.

    The main gaps left seem to be:

    1. docs/client.md (the 2025-11-25 client page) does not have an authorization section yet showing how to wire McpSyncHttpClientRequestCustomizer / McpAsyncHttpClientRequestCustomizer with transportContextProvider (or contextWrite(McpTransportContext.KEY, ...) on async) on HttpClientStreamableHttpTransport.
    2. docs/server.md shows addToolFilter under "Filtering the Tool Listing per Request" and notes that hidden tools can still be invoked directly, but stops short of showing the matching check in callHandler using exchange.transportContext().
    3. docs/server-modern.md mentions contextExtractor under "HTTP Security", and we could add a short example showing how a McpSyncToolRepository / McpAsyncToolRepository reads ctx.transportContext() in both list and find (or inside the tool handler) to enforce permissions per caller, plus a quick note leading people to spring-ai-community/mcp-security when they are on Spring Boot.

    I have worked extensively with OAuth2 and context propagation in Java MCP servers and would be happy to put together a PR for this if you'd like to assign it to me.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions