1- # Simple Streamable Private Gateway Example
1+ # Simple Private Gateway Example
22
3- A demonstration of how to use the MCP Python SDK as a streamable private gateway with optional authentication (OAuth or API Key) over streamable HTTP or SSE transport with custom extensions for private gateway connectivity (SNI hostname support).
3+ A demonstration of how to use the MCP Python SDK as a private gateway with optional API key authentication over streamable HTTP or SSE transport with custom extensions for private gateway connectivity (SNI hostname support).
44
55## Features
66
7- - Multiple authentication options:
8- - OAuth 2.0 authentication with PKCE
9- - API Key authentication (Bearer token or custom header)
10- - No authentication
7+ - Optional API Key authentication (Bearer token or custom header)
118- Supports both StreamableHTTP and SSE transports
129- Custom extensions for private gateway (SNI hostname) - ** Both transports**
1310- Can combine authentication + extensions (for authenticated private gateway)
@@ -17,25 +14,21 @@ A demonstration of how to use the MCP Python SDK as a streamable private gateway
1714## Installation
1815
1916``` bash
20- cd examples/clients/simple-streamable- private-gateway
17+ cd examples/clients/simple-private-gateway
2118uv sync --reinstall
2219```
2320
2421## Usage
2522
2623### 1. Start an MCP server
2724
28- You can use any MCP server with or without authentication . For example:
25+ You can use any MCP server. For example:
2926
3027``` bash
3128# Example without authentication - StreamableHTTP transport
3229cd examples/servers/simple-tool
3330uv run mcp-simple-tool --transport streamable-http --port 8081
3431
35- # Example with OAuth authentication
36- cd examples/servers/simple-auth
37- uv run mcp-simple-auth --transport streamable-http --port 3001
38-
3932# Or with SSE transport
4033cd examples/servers/simple-tool
4134uv run mcp-simple-tool --transport sse --port 8081
@@ -45,16 +38,16 @@ uv run mcp-simple-tool --transport sse --port 8081
4538
4639The client will interactively prompt you for:
4740
48- - Server port
49- - Server hostname (for SNI)
41+ - Server URL (or press Enter to configure port/protocol/hostname separately)
42+ - If you provide a full URL, it will be used directly
43+ - If you press Enter, you'll be prompted for: port, protocol, and hostname (for SNI)
5044- Transport type (streamable-http or sse)
51- - Authentication type (none, OAuth, or API Key)
52- - For OAuth: Client metadata URL (optional)
45+ - Authentication type (none or API Key)
5346- For API Key: API key value, header name, and format (Bearer or direct)
5447
5548``` bash
5649# Run the client interactively
57- uv run mcp-simple-streamable- private-gateway
50+ uv run mcp-simple-private-gateway
5851```
5952
6053Follow the prompts to configure your connection.
@@ -72,11 +65,13 @@ The client provides several commands:
7265### Example 1: Private Gateway without Authentication (StreamableHTTP)
7366
7467``` markdown
75- 🚀 Simple Streamable Private Gateway
68+ 🚀 Simple Private Gateway
7669
7770📝 Server Configuration
7871==================================================
72+ Server URL [ https://localhost:8081 ] :
7973Server port [ 8081] : 8081
74+ Protocol [ https] : https
8075Server hostname [ mcp.deepwiki.com] : mcp.deepwiki.com
8176
8277Transport type:
@@ -86,8 +81,7 @@ Select transport [1]: 1
8681
8782Authentication:
8883 1 . No authentication (default)
89- 2 . OAuth authentication
90- 3 . API Key authentication
84+ 2 . API Key authentication
9185Select authentication [ 1] : 1
9286==================================================
9387
@@ -123,69 +117,16 @@ mcp> quit
123117👋 Goodbye!
124118```
125119
126- ### Example 2: Private Gateway with OAuth Authentication (StreamableHTTP)
127-
128- ``` markdown
129- 🚀 Simple Streamable Private Gateway
130-
131- 📝 Server Configuration
132- ==================================================
133- Server port [ 8081] : 3001
134- Server hostname [ mcp.deepwiki.com] : auth.mcp.example.com
135-
136- Transport type:
137- 1 . streamable-http (default)
138- 2 . sse
139- Select transport [ 1] : 1
140-
141- Authentication:
142- 1 . No authentication (default)
143- 2 . OAuth authentication
144- 3 . API Key authentication
145- Select authentication [ 1] : 2
146- Client metadata URL (optional, press Enter to skip):
147- ==================================================
148-
149- 🔗 Connecting to: http://localhost:3001/mcp
150- 📡 Server hostname: auth.mcp.example.com
151- 🚀 Transport type: streamable-http
152- 🔐 Authentication: OAuth
153-
154- 🔐 Setting up OAuth authentication...
155- 🖥️ Started callback server on http://localhost:3030
156- 📡 Opening StreamableHTTP transport connection with extensions and auth...
157- Opening browser for authorization: http://localhost:3001/authorize ?...
158- ⏳ Waiting for authorization callback...
159- 🤝 Initializing MCP session...
160- ⚡ Starting session initialization...
161- ✨ Session initialization complete!
162-
163- ✅ Connected to MCP server at http://localhost:3001/mcp
164- Session ID: xyz789...
165-
166- 🎯 Interactive MCP Client (Private Gateway with Auth)
167- Commands:
168- list - List available tools
169- call <tool_name> [ args] - Call a tool
170- quit - Exit the client
171-
172- mcp> list
173- 📋 Available tools:
174- 1 . secure-echo
175- Description: Authenticated echo service
176-
177- mcp> quit
178- 👋 Goodbye!
179- ```
180-
181- ### Example 3: SSE Transport without Authentication
120+ ### Example 2: SSE Transport without Authentication
182121
183122``` markdown
184- 🚀 Simple Streamable Private Gateway
123+ 🚀 Simple Private Gateway
185124
186125📝 Server Configuration
187126==================================================
127+ Server URL [ https://localhost:8081 ] :
188128Server port [ 8081] : 8081
129+ Protocol [ https] : https
189130Server hostname [ mcp.deepwiki.com] : mcp.deepwiki.com
190131
191132Transport type:
@@ -195,8 +136,7 @@ Select transport [1]: 2
195136
196137Authentication:
197138 1 . No authentication (default)
198- 2 . OAuth authentication
199- 3 . API Key authentication
139+ 2 . API Key authentication
200140Select authentication [ 1] : 1
201141==================================================
202142
@@ -227,14 +167,16 @@ mcp> quit
227167👋 Goodbye!
228168```
229169
230- ### Example 4 : API Key Authentication with Bearer Token (StreamableHTTP)
170+ ### Example 3 : API Key Authentication with Bearer Token (StreamableHTTP)
231171
232172``` markdown
233- 🚀 Simple Streamable Private Gateway
173+ 🚀 Simple Private Gateway
234174
235175📝 Server Configuration
236176==================================================
177+ Server URL [ https://localhost:8081 ] :
237178Server port [ 8081] : 8081
179+ Protocol [ https] : https
238180Server hostname [ mcp.deepwiki.com] : api.mcp.example.com
239181
240182Transport type:
@@ -244,9 +186,8 @@ Select transport [1]: 1
244186
245187Authentication:
246188 1 . No authentication (default)
247- 2 . OAuth authentication
248- 3 . API Key authentication
249- Select authentication [ 1] : 3
189+ 2 . API Key authentication
190+ Select authentication [ 1] : 2
250191Enter API key: sk-1234567890abcdef
251192
252193API Key format:
@@ -286,14 +227,16 @@ mcp> quit
286227👋 Goodbye!
287228```
288229
289- ### Example 5 : API Key Authentication with Custom Header (SSE)
230+ ### Example 4 : API Key Authentication with Custom Header (SSE)
290231
291232``` markdown
292- 🚀 Simple Streamable Private Gateway
233+ 🚀 Simple Private Gateway
293234
294235📝 Server Configuration
295236==================================================
237+ Server URL [ https://localhost:8081 ] :
296238Server port [ 8081] : 8082
239+ Protocol [ https] : https
297240Server hostname [ mcp.deepwiki.com] : custom.mcp.example.com
298241
299242Transport type:
@@ -303,9 +246,8 @@ Select transport [1]: 2
303246
304247Authentication:
305248 1 . No authentication (default)
306- 2 . OAuth authentication
307- 3 . API Key authentication
308- Select authentication [ 1] : 3
249+ 2 . API Key authentication
250+ Select authentication [ 1] : 2
309251Enter API key: my-secret-api-key-123
310252
311253API Key format:
@@ -349,13 +291,17 @@ mcp> quit
349291
350292The client uses interactive prompts for configuration. You'll be asked to provide:
351293
352- - ** Server port** : The port where your MCP server is running (default: 8081)
353- - ** Server hostname** : The hostname for SNI (Server Name Indication) used in private gateway setup (default: mcp.deepwiki.com)
294+ - ** Server URL** : The full URL of your MCP server (default: https://localhost:8081 )
295+ - If you provide a URL, it will be used directly
296+ - If you press Enter (empty), you'll be prompted for individual components:
297+ - ** Server port** : The port where your MCP server is running (default: 8081)
298+ - ** Protocol** : The protocol to use (default: https)
299+ - ** Server hostname** : The hostname for SNI (Server Name Indication) used in private gateway setup (default: mcp.deepwiki.com)
354300- ** Transport type** : Choose between ` streamable-http ` or ` sse ` (default: streamable-http)
301+ - StreamableHTTP servers typically use ` /mcp ` endpoint
302+ - SSE servers typically use ` /sse ` endpoint
355303- ** Authentication** : Choose authentication method (default: no authentication)
356304 - ** None** : No authentication
357- - ** OAuth** : OAuth 2.0 with PKCE
358- - ** Client metadata URL** : Optional URL for OAuth client metadata
359305 - ** API Key** : API key-based authentication
360306 - ** API Key** : Your API key value
361307 - ** Format** : Bearer token (Authorization: Bearer <key >) or custom header
@@ -366,7 +312,5 @@ The client uses interactive prompts for configuration. You'll be asked to provid
366312This client supports multiple scenarios:
367313
3683141 . ** Private Gateway without Auth** : Use custom SNI hostname for HTTPS private gateway connectivity
369- 2 . ** Private Gateway with OAuth** : Combine OAuth 2.0 authentication with private gateway extensions
370- 3 . ** Private Gateway with API Key** : Use API key authentication (Bearer or custom header) with private gateway
371- 4 . ** Standard Server with Auth** : Use OAuth or API Key authentication without private gateway extensions
372- 5 . ** Both Transports** : Works with both StreamableHTTP and SSE transports in all scenarios
315+ 2 . ** Private Gateway with API Key** : Use API key authentication (Bearer or custom header) with private gateway
316+ 3 . ** Both Transports** : Works with both StreamableHTTP and SSE transports in all scenarios
0 commit comments