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) andecho(echoes message with user name)
Quick Start
1. Start the Server (Docker)```bash
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`:```json
{
"mcpServers": {
"oauth-toy": {
"url": "http://localhost:8000/mcp",
"oauth": true
}
}
}
3. Test with mcp-cli```bash
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.```bash
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.```bash
mcp-cli -c ~/.config/mcp/mcp_servers.json oauth-toy/echo '{"message": "Hello!"}'
Output: Alice says: Hello!
## Local Development
### Using uv```bash
# Install dependencies
uv sync
# Run the server
uv run python -m mcp_server_oauth_toy
Using Docker Compose```bash
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:```json
{
"mcpServers": {
"oauth-toy": {
"url": "https://your-deployment.vercel.app/mcp",
"oauth": true
}
}
}
License
MIT