Skip to content

docs(samples): add simple OAuth client sample (#166) - #1173

Open
Rutvij97 wants to merge 1 commit into
modelcontextprotocol:mainfrom
Rutvij97:feat/simple-oauth-client-sample
Open

Rutvij97 wants to merge 1 commit into
modelcontextprotocol:mainfrom
Rutvij97:feat/simple-oauth-client-sample

Conversation

@Rutvij97

@Rutvij97 Rutvij97 commented Nov 10, 2026 •

Copy link
Copy Markdown

Closes #166.

Adds samples/simple-oauth-client, a command-line client that signs in to an OAuth-protected MCP server over Streamable HTTP. The SDK doesn't ship client-side OAuth yet, so the sample implements the MCP authorization flow with plain Ktor:

  • A Ktor HttpSend interceptor adds the bearer token. On 401 it runs the flow and retries once.
  • It discovers the protected resource metadata (RFC 9728), using the resource_metadata hint from WWW-Authenticate, then the authorization server metadata (RFC 8414, with OIDC as a fallback).
  • It registers a public client dynamically (RFC 7591). MCP_CLIENT_ID / MCP_CLIENT_SECRET can be used instead.
  • It runs the authorization code flow with PKCE S256 and a state check, receiving the code on a loopback redirect (http://127.0.0.1:<port>/callback).
  • It exchanges the code with the resource parameter (RFC 8707), then lists tools and optionally calls one.

samples/README.md now lists the new sample.

I left the CI sample matrices in build.yml and samples.yml untouched. Happy to add simple-oauth-client to them if you'd like it built in CI.

Testing

  • OAuthClientTest runs the full flow against an in-process MCP server. The server is the SDK's mcpStreamableHttp with a whoami tool, guarded by a minimal authorization server that checks the PKCE verifier, redirect URI and resource. The test also covers state mismatch rejection, the RFC 7636 S256 test vector and WWW-Authenticate parsing.
  • ./gradlew build in samples/simple-oauth-client (JDK 21) passes: 4 tests.
  • ktlint 1.8.0 with the repository .editorconfig reports no issues.

Add samples/simple-oauth-client, a command-line client that signs in to an
OAuth-protected MCP server over Streamable HTTP. On a 401 it discovers the
protected resource and authorization server metadata, registers a public
client dynamically, runs the authorization code flow with PKCE on a loopback
redirect, exchanges the code with the resource parameter and retries.

The test runs the full flow against an in-process MCP server guarded by a
minimal authorization server.
@Rutvij97
Rutvij97 force-pushed the feat/simple-oauth-client-sample branch from d050792 to 52f3af1 Compare November 10, 2026 21:20

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Client example - simple oauth

1 participant