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)

Related MCP server: SkyStage MCP Test Server

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

MCP Endpoints

Environment Variables

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