examples: bind local servers to localhost by default

Author: Theodor N. Engøy

examples/client/README.md

@@ -20,6 +20,8 @@ cd examples/client
 pnpm tsx src/simpleStreamableHttp.ts
 ```
 
+By default, examples that start a local OAuth callback server bind to `localhost`. To bind to a different interface, set `MCP_HOST` (for example `MCP_HOST=127.0.0.1`).
+
 Most clients expect a server to be running. Start one from [`../server/README.md`](../server/README.md) (for example `src/simpleStreamableHttp.ts` in `examples/server`).
 
 ## Example index

examples/client/src/elicitationUrlExample.ts

@@ -34,7 +34,8 @@ import { InMemoryOAuthClientProvider } from './simpleOAuthClientProvider.js';
 
 // Set up OAuth (required for this example)
 const OAUTH_CALLBACK_PORT = 8090; // Use different port than auth server (3001)
-const OAUTH_CALLBACK_URL = `http://localhost:${OAUTH_CALLBACK_PORT}/callback`;
+const OAUTH_CALLBACK_HOST = process.env.MCP_HOST ?? 'localhost';
+const OAUTH_CALLBACK_URL = `http://${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}/callback`;
 
 console.log('Getting OAuth token...');
 const clientMetadata: OAuthClientMetadata = {
@@ -484,8 +485,8 @@ async function waitForOAuthCallback(): Promise<string> {
             }
         });
 
-        server.listen(OAUTH_CALLBACK_PORT, () => {
-            console.log(`OAuth callback server started on http://localhost:${OAUTH_CALLBACK_PORT}`);
+        server.listen(OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_HOST, () => {
+            console.log(`OAuth callback server started on ${OAUTH_CALLBACK_URL}`);
         });
     });
 }

examples/client/src/simpleOAuthClient.ts

@@ -19,7 +19,8 @@ import { InMemoryOAuthClientProvider } from './simpleOAuthClientProvider.js';
 // Configuration
 const DEFAULT_SERVER_URL = 'http://localhost:3000/mcp';
 const CALLBACK_PORT = 8090; // Use different port than auth server (3001)
-const CALLBACK_URL = `http://localhost:${CALLBACK_PORT}/callback`;
+const CALLBACK_HOST = process.env.MCP_HOST ?? 'localhost';
+const CALLBACK_URL = `http://${CALLBACK_HOST}:${CALLBACK_PORT}/callback`;
 
 /**
  * Interactive MCP client with OAuth authentication
@@ -118,8 +119,8 @@ class InteractiveOAuthClient {
                 }
             });
 
-            server.listen(CALLBACK_PORT, () => {
-                console.log(`OAuth callback server started on http://localhost:${CALLBACK_PORT}`);
+            server.listen(CALLBACK_PORT, CALLBACK_HOST, () => {
+                console.log(`OAuth callback server started on ${CALLBACK_URL}`);
             });
         });
     }

examples/server/README.md

@@ -16,6 +16,8 @@ pnpm install
 pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts
 ```
 
+By default, example servers bind to `localhost`. To bind to a different interface, set `MCP_HOST` (for example `MCP_HOST=0.0.0.0`).
+
 Or, from within this package:
 
 ```bash

examples/server/src/customProtocolVersion.ts

@@ -51,15 +51,23 @@ const transport = new NodeStreamableHTTPServerTransport({
 await server.connect(transport);
 
 // Simple HTTP server
+const HOST = process.env.MCP_HOST ?? 'localhost';
 const PORT = process.env.MCP_PORT ? Number.parseInt(process.env.MCP_PORT, 10) : 3000;
 
-createServer(async (req, res) => {
+const httpServer = createServer(async (req, res) => {
     if (req.url === '/mcp') {
         await transport.handleRequest(req, res);
     } else {
         res.writeHead(404).end('Not Found');
     }
-}).listen(PORT, () => {
-    console.log(`MCP server with custom protocol versions on port ${PORT}`);
+});
+
+httpServer.listen(PORT, HOST, () => {
+    console.log(`MCP server with custom protocol versions on http://${HOST}:${PORT}/mcp`);
     console.log(`Supported versions: ${CUSTOM_VERSIONS.join(', ')}`);
 });
+httpServer.on('error', error => {
+    console.error('Failed to start server:', error);
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(1);
+});

examples/server/src/elicitationFormExample.ts

@@ -315,9 +315,10 @@ mcpServer.registerTool(
 );
 
 async function main() {
+    const HOST = process.env.MCP_HOST ?? 'localhost';
     const PORT = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000;
 
-    const app = createMcpExpressApp();
+    const app = createMcpExpressApp({ host: HOST });
 
     // Map to store transports by session ID
     const transports: { [sessionId: string]: NodeStreamableHTTPServerTransport } = {};
@@ -430,19 +431,19 @@ async function main() {
     app.delete('/mcp', mcpDeleteHandler);
 
     // Start listening
-    app.listen(PORT, error => {
-        if (error) {
-            console.error('Failed to start server:', error);
-            // eslint-disable-next-line unicorn/no-process-exit
-            process.exit(1);
-        }
-        console.log(`Form elicitation example server is running on http://localhost:${PORT}/mcp`);
+    const httpServer = app.listen(PORT, HOST, () => {
+        console.log(`Form elicitation example server is running on http://${HOST}:${PORT}/mcp`);
         console.log('Available tools:');
         console.log('  - register_user: Collect user registration information');
         console.log('  - create_event: Multi-step event creation');
         console.log('  - update_shipping_address: Collect and validate address');
         console.log('\nConnect your MCP client to this server using the HTTP transport.');
     });
+    httpServer.on('error', error => {
+        console.error('Failed to start server:', error);
+        // eslint-disable-next-line unicorn/no-process-exit
+        process.exit(1);
+    });
 
     // Handle server shutdown
     process.on('SIGINT', async () => {

examples/server/src/elicitationUrlExample.ts

@@ -215,10 +215,11 @@ function completeURLElicitation(elicitationId: string) {
     elicitation.completeResolver();
 }
 
+const MCP_HOST = process.env.MCP_HOST ?? 'localhost';
 const MCP_PORT = process.env.MCP_PORT ? Number.parseInt(process.env.MCP_PORT, 10) : 3000;
 const AUTH_PORT = process.env.MCP_AUTH_PORT ? Number.parseInt(process.env.MCP_AUTH_PORT, 10) : 3001;
 
-const app = createMcpExpressApp();
+const app = createMcpExpressApp({ host: MCP_HOST });
 
 // Allow CORS all domains, expose the Mcp-Session-Id header
 app.use(
@@ -703,14 +704,14 @@ const mcpDeleteHandler = async (req: Request, res: Response) => {
 // Set up DELETE route with auth middleware
 app.delete('/mcp', authMiddleware, mcpDeleteHandler);
 
-app.listen(MCP_PORT, error => {
-    if (error) {
-        console.error('Failed to start server:', error);
-        // eslint-disable-next-line unicorn/no-process-exit
-        process.exit(1);
-    }
-    console.log(`MCP Streamable HTTP Server listening on port ${MCP_PORT}`);
-    console.log(`  Protected Resource Metadata: http://localhost:${MCP_PORT}/.well-known/oauth-protected-resource/mcp`);
+const httpServer = app.listen(MCP_PORT, MCP_HOST, () => {
+    console.log(`MCP Streamable HTTP Server listening on http://${MCP_HOST}:${MCP_PORT}/mcp`);
+    console.log(`  Protected Resource Metadata: http://${MCP_HOST}:${MCP_PORT}/.well-known/oauth-protected-resource/mcp`);
+});
+httpServer.on('error', error => {
+    console.error('Failed to start server:', error);
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(1);
 });
 
 // Handle server shutdown

examples/server/src/honoWebStandardStreamableHttp.ts

@@ -59,15 +59,17 @@ app.get('/health', c => c.json({ status: 'ok' }));
 app.all('/mcp', c => transport.handleRequest(c.req.raw));
 
 // Start the server
+const HOST = process.env.MCP_HOST ?? 'localhost';
 const PORT = process.env.MCP_PORT ? Number.parseInt(process.env.MCP_PORT, 10) : 3000;
 
 await server.connect(transport);
 
-console.log(`Starting Hono MCP server on port ${PORT}`);
-console.log(`Health check: http://localhost:${PORT}/health`);
-console.log(`MCP endpoint: http://localhost:${PORT}/mcp`);
+console.log(`Starting Hono MCP server on http://${HOST}:${PORT}`);
+console.log(`Health check: http://${HOST}:${PORT}/health`);
+console.log(`MCP endpoint: http://${HOST}:${PORT}/mcp`);
 
 serve({
     fetch: app.fetch,
+    hostname: HOST,
     port: PORT
 });

examples/server/src/jsonResponseStreamableHttp.ts

@@ -77,7 +77,10 @@ const getServer = () => {
     return server;
 };
 
-const app = createMcpExpressApp();
+const HOST = process.env.MCP_HOST ?? 'localhost';
+const PORT = process.env.MCP_PORT ? Number.parseInt(process.env.MCP_PORT, 10) : 3000;
+
+const app = createMcpExpressApp({ host: HOST });
 
 // Map to store transports by session ID
 const transports: { [sessionId: string]: NodeStreamableHTTPServerTransport } = {};
@@ -148,14 +151,13 @@ app.get('/mcp', async (req: Request, res: Response) => {
 });
 
 // Start the server
-const PORT = 3000;
-app.listen(PORT, error => {
-    if (error) {
-        console.error('Failed to start server:', error);
-        // eslint-disable-next-line unicorn/no-process-exit
-        process.exit(1);
-    }
-    console.log(`MCP Streamable HTTP Server listening on port ${PORT}`);
+const server = app.listen(PORT, HOST, () => {
+    console.log(`MCP Streamable HTTP Server listening on http://${HOST}:${PORT}/mcp`);
+});
+server.on('error', error => {
+    console.error('Failed to start server:', error);
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(1);
 });
 
 // Handle server shutdown

examples/server/src/simpleStatelessStreamableHttp.ts

@@ -94,7 +94,10 @@ const getServer = () => {
     return server;
 };
 
-const app = createMcpExpressApp();
+const HOST = process.env.MCP_HOST ?? 'localhost';
+const PORT = process.env.MCP_PORT ? Number.parseInt(process.env.MCP_PORT, 10) : 3000;
+
+const app = createMcpExpressApp({ host: HOST });
 
 app.post('/mcp', async (req: Request, res: Response) => {
     const server = getServer();
@@ -153,14 +156,13 @@ app.delete('/mcp', async (req: Request, res: Response) => {
 });
 
 // Start the server
-const PORT = 3000;
-app.listen(PORT, error => {
-    if (error) {
-        console.error('Failed to start server:', error);
-        // eslint-disable-next-line unicorn/no-process-exit
-        process.exit(1);
-    }
-    console.log(`MCP Stateless Streamable HTTP Server listening on port ${PORT}`);
+const server = app.listen(PORT, HOST, () => {
+    console.log(`MCP Stateless Streamable HTTP Server listening on http://${HOST}:${PORT}/mcp`);
+});
+server.on('error', error => {
+    console.error('Failed to start server:', error);
+    // eslint-disable-next-line unicorn/no-process-exit
+    process.exit(1);
 });
 
 // Handle server shutdown