Unified MCP Gateway
Overview & Architecture
The Unified MCP Gateway aggregates multiple upstream MCP (Model Context Protocol) servers behind a single HTTP endpoint. Clients connect once to LocalRouter and gain access to tools, resources, and prompts from all configured MCP servers without managing individual connections.
The gateway handles connection lifecycle, transport differences, authentication, and error isolation — if one upstream server fails, others continue working.
Tool Namespacing (server__tool)
To avoid naming collisions across MCP servers, the gateway prefixes every tool name with the server's ID using a double-underscore separator: {server_id}__{tool_name}. For example, a search tool from a server named brave becomes brave__search.
When a tools/call request arrives, the gateway strips the prefix to identify the target server and original tool name. This namespacing is transparent to upstream servers — they receive calls with their original tool names.
Transport Types
The MCP gateway supports STDIO, Streamable HTTP (including legacy HTTP+SSE), and a WebSocket extension for connecting to upstream MCP servers. Each transport is configured per-server and handles connection establishment, message framing, and reconnection differently.
STDIO
STDIO transport launches the MCP server as a child process and communicates via stdin/stdout pipes. This is the most common transport for local tools like file system access, databases, or CLI wrappers.
The gateway manages the process lifecycle — starting the process on first use, monitoring for crashes, and restarting as needed. Environment variables (including auth credentials) can be passed to the subprocess at launch.
SSE
SSE (Server-Sent Events) transport connects to a remote MCP server over HTTP. The client sends JSON-RPC requests via POST and receives responses through a persistent SSE stream.
This transport is suitable for remote MCP servers that use the older SSE-based MCP transport specification.
Streamable HTTP
Streamable HTTP is the modern MCP transport that uses standard HTTP POST requests with optional SSE streaming for responses. Each request is a standalone HTTP call, and the server can respond with a direct JSON response or upgrade to SSE for streaming.
This is the recommended transport for new remote MCP server implementations. Select HTTP (Streamable HTTP / SSE) and enter the complete endpoint URL. Paths such as Atlassian’s /v2/mcp are service-specific; MCP protocol revisions are declared in requests.
Choose OAuth (Browser login) to sign in through the provider’s login page. LocalRouter discovers the authorization server, registers a native public client where supported, uses PKCE, and stores tokens in the system keychain. Servers that require a registered client ID can be configured through OAuth client settings. Expired browser credentials are refreshed when reconnecting.
The Atlassian template uses https://mcp.atlassian.com/v2/mcp. The Datadog template uses https://mcp.datadoghq.com/api/unstable/mcp-server/mcp and provides toolset selection, including DDSQL (?toolsets=ddsql). Both templates use browser login.
Deferred Tool Loading
By default, MCP server connections are deferred until first use. When LocalRouter starts, it does not immediately connect to all configured MCP servers — instead, it waits until a client sends a tools/list request or calls a tool on that server.
This reduces startup time and avoids errors from servers that may not be running. Once a server is accessed, its tools are cached until the connection is refreshed or the server is restarted.
Virtual Search Tool
When many MCP servers are configured (10+), the combined tool list can become very large, consuming excessive context in LLM conversations.
The virtual search tool addresses this by exposing a single localrouter__search_tools meta-tool that lets LLMs search across all available tools by keyword. Instead of receiving hundreds of tool definitions upfront, the LLM can query for relevant tools on demand. The search matches against tool names, descriptions, and server names.
Session Management
The MCP gateway maintains per-client sessions to track state across multiple requests. Each client connection gets a unique session ID (returned via the Mcp-Session-Id header) that maps to its upstream server connections and cached data.
Legacy MCP clients use initialization and HTTP session IDs. MCP 2026-07-28 clients use stateless per-request metadata and server/discover; change notifications use an explicitly filtered subscriptions/listen POST stream. LocalRouter adapts between these revisions and cleans up internal routing state after inactivity.
Response Caching
The gateway caches responses from upstream MCP servers to reduce latency and avoid redundant calls. Tool lists are cached per-server and invalidated when the server signals a change or the cache expires. Resource contents can also be cached.
Caching is transparent to clients — they always receive fresh-looking responses while the gateway handles staleness checks behind the scenes.
Partial Failure Handling
When a request spans multiple upstream servers (e.g., tools/list aggregates from all servers), the gateway handles partial failures gracefully. If one server is unreachable, tools from healthy servers are still returned — the failed server's tools are simply omitted.
For tools/call targeting a specific server, a failure is returned directly to the client since there's no fallback.
MCP OAuth Browser Authentication
For remote MCP servers that require OAuth authentication, LocalRouter implements a full OAuth 2.0 client flow with PKCE (Proof Key for Code Exchange).
This handles the complete browser-based authentication flow — opening the authorization URL, receiving the callback, exchanging the code for tokens, and storing them securely. OAuth configuration can be provided explicitly or discovered automatically from the server's well-known metadata endpoint.
OAuth 2.0 + PKCE Flow
The OAuth PKCE flow opens a browser window where you grant access to the MCP server. After authorization, LocalRouter receives an access token and refresh token, stored securely in the keychain.
PKCE prevents authorization code interception attacks without requiring a client secret, making it suitable for desktop applications.
Auto-Discovery
When an MCP server requires OAuth but no explicit configuration is provided, LocalRouter attempts auto-discovery by fetching the server's /.well-known/oauth-authorization-server metadata document.
If discovery succeeds, the OAuth flow is configured automatically without requiring manual endpoint setup.
Token Refresh
Access tokens from OAuth flows have limited lifetimes (typically 1 hour). When a token expires, LocalRouter automatically uses the stored refresh token to obtain a new access token without requiring any action from you.
If the refresh token itself expires or is revoked, you'll be prompted to re-authenticate through the browser flow.