MCP Server OAuth Toy

A simple MCP (Model Context Protocol) server with OAuth 2.0 authentication for testing the OAuth support in mcp-cli.

Features

• Full OAuth 2.0 Authorization Code flow with PKCE
• Dynamic client registration (RFC 7591)
• In-memory session storage (for testing)
• Browser-based authorization where users enter their name
• Two tools: whoami (returns authenticated user) and echo (echoes message with user name)

Quick Start

1. Start the Server (Docker)

# Clone the repository
git clone https://github.com/bvolpato/mcp-server-oauth-toy.git
cd mcp-server-oauth-toy

# Build and run with Docker
docker build -t mcp-server-oauth-toy .
docker run -p 8000:8000 mcp-server-oauth-toy

2. Configure mcp-cli

Add to your ~/.config/mcp/mcp_servers.json:

{
  "mcpServers": {
    "oauth-toy": {
      "url": "http://localhost:8000/mcp",
      "oauth": true
    }
  }
}

3. Test with mcp-cli

# Install mcp-cli (requires Bun)
bun install -g @philschmid/mcp-cli

# List available tools (will trigger OAuth flow on first run)
mcp-cli -c ~/.config/mcp/mcp_servers.json oauth-toy

# Call the whoami tool
mcp-cli -c ~/.config/mcp/mcp_servers.json oauth-toy/whoami '{}'

# Call the echo tool
mcp-cli -c ~/.config/mcp/mcp_servers.json oauth-toy/echo '{"message": "Hello!"}'

OAuth Flow

When you first connect to the server:

1. mcp-cli detects the server requires OAuth (401 response)
2. mcp-cli discovers OAuth endpoints via /.well-known/oauth-authorization-server
3. mcp-cli registers as a client via /register (dynamic registration)
4. Your browser opens to the authorization page
5. You enter your name and click "Authorize"
6. mcp-cli receives the authorization code and exchanges it for tokens
7. Subsequent requests use the stored access token

Tools

whoami

Returns the name of the authenticated user.

mcp-cli -c ~/.config/mcp/mcp_servers.json oauth-toy/whoami '{}'
# Output: You are authenticated as: Alice

echo

Echoes back the provided message with the authenticated user's name.

mcp-cli -c ~/.config/mcp/mcp_servers.json oauth-toy/echo '{"message": "Hello!"}'
# Output: Alice says: Hello!

Local Development

Using uv

# Install dependencies
uv sync

# Run the server
uv run python -m mcp_server_oauth_toy

Using Docker Compose

docker-compose up

OAuth Endpoints

Endpoint	Description
/.well-known/oauth-authorization-server	OAuth 2.0 Authorization Server Metadata
/register	Dynamic Client Registration
/authorize	Authorization endpoint (shows login form)
/token	Token endpoint

MCP Endpoints

Endpoint	Description
/mcp	MCP over Streamable HTTP
/health	Health check

Environment Variables

Variable	Default	Description
HOST	0.0.0.0	Server host
PORT	8000	Server port
BASE_URL	http://localhost:8000	Public base URL
REDIS_URL	(none)	Redis URL for persistent storage (e.g., Upstash)
KV_URL	(none)	Alternative Redis URL (Vercel KV)

Persistent Storage (for Serverless)

By default, the server uses in-memory storage which doesn't persist across serverless function invocations. For production use on Vercel, set up Redis:

Using Upstash (Recommended)

1. Create a free Redis database at upstash.com
2. Copy the UPSTASH_REDIS_REST_URL
3. Add it as REDIS_URL in your Vercel environment variables

Using Vercel KV

1. Add Vercel KV to your project from the Vercel dashboard
2. The KV_URL environment variable is automatically set

Testing the PR

This server was created to test mcp-cli PR #18 which adds OAuth support.

To test the OAuth implementation:

1. Start this server locally
2. Use mcp-cli with the oauth: true configuration
3. Complete the browser-based authorization
4. Verify the whoami tool returns your name

Deploy to Vercel

1. Click the button above or import the repo at vercel.com/new
2. Select "Other" as the framework (Vercel auto-detects Python)
3. Deploy!

The BASE_URL is automatically set from VERCEL_URL.

Then update your mcp_servers.json:

{
  "mcpServers": {
    "oauth-toy": {
      "url": "https://your-deployment.vercel.app/mcp",
      "oauth": true
    }
  }
}

License

MIT