Skip to content

docs: fix simple-auth README references to non-existent scripts #1829

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pcarleton merged 1 commit into from
Jan 8, 2026
+51 −26
Merged

docs: fix simple-auth README references to non-existent scripts #1829

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 45 additions & 21 deletions examples/clients/simple-auth-client/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,63 +12,87 @@ A demonstration of how to use the MCP Python SDK with OAuth authentication over

```bash
cd examples/clients/simple-auth-client
uv sync --reinstall
uv sync --reinstall
```

## Usage

### 1. Start an MCP server with OAuth support

The simple-auth server example provides three server configurations. See [examples/servers/simple-auth/README.md](../../servers/simple-auth/README.md) for full details.

#### Option A: New Architecture (Recommended)

Separate Authorization Server and Resource Server:

```bash
# Terminal 1: Start Authorization Server on port 9000
cd examples/servers/simple-auth
uv run mcp-simple-auth-as --port=9000

# Terminal 2: Start Resource Server on port 8001
cd examples/servers/simple-auth
uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http
```

#### Option B: Legacy Server (Backwards Compatibility)

```bash
# Example with mcp-simple-auth
cd path/to/mcp-simple-auth
uv run mcp-simple-auth --transport streamable-http --port 3001
# Single server that acts as both AS and RS (port 8000)
cd examples/servers/simple-auth
uv run mcp-simple-auth-legacy --port=8000 --transport=streamable-http
```

### 2. Run the client

```bash
uv run mcp-simple-auth-client
# Connect to Resource Server (new architecture, default port 8001)
MCP_SERVER_PORT=8001 uv run mcp-simple-auth-client

# Or with custom server URL
MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client
# Connect to Legacy Server (port 8000)
uv run mcp-simple-auth-client

# Use SSE transport
MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
MCP_SERVER_PORT=8001 MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
```

### 3. Complete OAuth flow

The client will open your browser for authentication. After completing OAuth, you can use commands:

- `list` - List available tools
- `call <tool_name> [args]` - Call a tool with optional JSON arguments
- `call <tool_name> [args]` - Call a tool with optional JSON arguments
- `quit` - Exit

## Example

```markdown
🔐 Simple MCP Auth Client
Connecting to: http://localhost:3001
🚀 Simple MCP Auth Client
Connecting to: http://localhost:8001/mcp
Transport type: streamable-http

Please visit the following URL to authorize the application:
http://localhost:3001/authorize?response_type=code&client_id=...
🔗 Attempting to connect to http://localhost:8001/mcp...
📡 Opening StreamableHTTP transport connection with auth...
Opening browser for authorization: http://localhost:9000/authorize?...

✅ Connected to MCP server at http://localhost:3001
✅ Connected to MCP server at http://localhost:8001/mcp

mcp> list
📋 Available tools:
1. echo - Echo back the input text
1. get_time
Description: Get the current server time.

mcp> call echo {"text": "Hello, world!"}
🔧 Tool 'echo' result:
Hello, world!
mcp> call get_time
🔧 Tool 'get_time' result:
{"current_time": "2024-01-15T10:30:00", "timezone": "UTC", ...}

mcp> quit
👋 Goodbye!
```

## Configuration

- `MCP_SERVER_PORT` - Server URL (default: 8000)
- `MCP_TRANSPORT_TYPE` - Transport type: `streamable-http` (default) or `sse`
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `MCP_SERVER_PORT` | Port number of the MCP server | `8000` |
| `MCP_TRANSPORT_TYPE` | Transport type: `streamable-http` or `sse` | `streamable-http` |
| `MCP_CLIENT_METADATA_URL` | Optional URL for client metadata (CIMD) | None |
11 changes: 6 additions & 5 deletions examples/servers/simple-auth/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@ uv run mcp-simple-auth-as --port=9000
cd examples/servers/simple-auth

# Start Resource Server on port 8001, connected to Authorization Server
uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http
uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http

# With RFC 8707 strict resource validation (recommended for production)
uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http --oauth-strict
uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http --oauth-strict

```

Expand Down Expand Up @@ -84,8 +84,9 @@ For backwards compatibility with older MCP implementations, a legacy server is p
### Running the Legacy Server

```bash
# Start legacy authorization server on port 8002
uv run mcp-simple-auth-legacy --port=8002
# Start legacy server on port 8000 (the default)
cd examples/servers/simple-auth
uv run mcp-simple-auth-legacy --port=8000 --transport=streamable-http
```

**Differences from the new architecture:**
Expand All @@ -101,7 +102,7 @@ uv run mcp-simple-auth-legacy --port=8002
```bash
# Test with client (will automatically fall back to legacy discovery)
cd examples/clients/simple-auth-client
MCP_SERVER_PORT=8002 MCP_TRANSPORT_TYPE=streamable-http uv run mcp-simple-auth-client
MCP_SERVER_PORT=8000 MCP_TRANSPORT_TYPE=streamable-http uv run mcp-simple-auth-client
```

The client will:
Expand Down