{"slug":"mcp-server-proxying","title":"MCP server proxying","tags":["tailscale"],"agent_summary":"Last validated: Mar 30, 2026","trigger_phrases":[],"runnable":false,"markdown":"\r\n# MCP server proxying\r\n\r\nLast validated: Mar 30, 2026\r\n\r\nAperture MCP server proxyingis currently [in alpha](https://tailscale.com/docs/reference/tailscale-release-stages#alpha).\r\n\r\nAperture can aggregate tools and resources from multiple remote [Model Context Protocol](https://modelcontextprotocol.io/specification) (MCP) servers and expose them to AI agents through a single `/v1/mcp` endpoint. This lets you centralize MCP tool management behind your Aperture proxy with the same identity-based access control used for LLM providers.\r\n\r\nAperture acts as an MCP server when communicating with AI agent clients and as an MCP client when communicating with remote MCP servers. Clients connect to Aperture's `/v1/mcp` endpoint and access an aggregated view of all tools and resources from every configured remote server.\r\n\r\n## [Use cases](https://tailscale.com/docs/aperture/mcp-server\\#use-cases)\r\n\r\nMCP server proxying addresses the following use cases:\r\n\r\n- **Centralized tool access**: Aggregate tools from multiple MCP servers behind a single endpoint. AI agents connect to one URL instead of managing connections to each server individually.\r\n- **Identity-based access control**: Control which users can access which MCP tools and resources using the same Tailscale identity and grants system used for LLM providers.\r\n- **Dynamic tool discovery**: Register and unregister MCP servers at runtime. When a server comes online, its tools become available automatically. When it goes offline, Aperture removes its tools.\r\n- **Protocol compatibility**: Connect MCP servers that use different protocol versions. Aperture auto-detects whether each server supports Streamable HTTP or legacy SSE and handles the translation.\r\n\r\n## [Key MCP concepts](https://tailscale.com/docs/aperture/mcp-server\\#key-mcp-concepts)\r\n\r\nThe [Model Context Protocol](https://modelcontextprotocol.io/specification) defines a standard way for AI agents to discover and use external capabilities. The following concepts are relevant to configuring MCP in Aperture:\r\n\r\n- **Tools**: Functions that LLMs can discover and call, such as searching a database or running a command.\r\n- **Resources**: Contextual data identified by URI that LLMs can read, such as file contents or API responses.\r\n- **Streamable HTTP**: The current MCP transport protocol that uses a single HTTP endpoint for bidirectional communication.\r\n- **Legacy SSE**: The deprecated MCP transport that uses Server-Sent Events. Aperture supports both transports for backward compatibility.\r\n\r\n## [Prerequisites](https://tailscale.com/docs/aperture/mcp-server\\#prerequisites)\r\n\r\nBefore you can use MCP server proxying, you need the following:\r\n\r\n- Aperture enabled on your [tailnet](https://tailscale.com/docs/concepts/tailnet). Refer to [get started with Aperture](https://tailscale.com/docs/aperture#get-started) if you have not set this up.\r\n- At least one remote MCP server accessible from the Aperture host (in the tailnet or on localhost).\r\n- The URL of each MCP server's endpoint (for example, `http://localhost:8185/v1/mcp` or `http://mcp-server.example.ts.net:8080/v1/mcp`).\r\n\r\n## [Get started](https://tailscale.com/docs/aperture/mcp-server\\#get-started)\r\n\r\nTo configure MCP server proxying in Aperture, add remote servers, grant users access to MCP tools, and connect an MCP client.\r\n\r\n### [Step 1: Configure MCP servers](https://tailscale.com/docs/aperture/mcp-server\\#step-1-configure-mcp-servers)\r\n\r\nOpen the **Settings** page of the Aperture dashboard and add an `mcp` section to your configuration with one or more remote servers.\r\n\r\n```json\r\n{\r\n \"mcp\": {\r\n \"servers\": {\r\n \"local\": {\r\n \"url\": \"http://localhost:8185/v1/mcp\"\r\n },\r\n \"remote\": {\r\n \"url\": \"http://mcp-server.example.ts.net:8080/v1/mcp\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\nEach key in the `servers` map is a server ID that Aperture uses as a name prefix. For the configuration above:\r\n\r\n- Tools from the `local` server are prefixed with `local_` (for example, a tool named `search` becomes `local_search`).\r\n- Tools from the `remote` server are prefixed with `remote_` (for example, `get_user` becomes `remote_get_user`).\r\n- Resources use a hyphen instead of an underscore (for example, `local-files://readme.md`).\r\n\r\nName prefixing prevents collisions when multiple servers expose tools with the same name. Clients receive the prefixed names and Aperture automatically strips the prefix when forwarding calls to the remote server.\r\n\r\nThe Aperture host uses its tailnet HTTP client for connections to remote MCP servers, so you can use tailnet hostnames (for example, `http://mcp-server.example.ts.net:8080/v1/mcp`) without additional network configuration.\r\n\r\n### [Step 2: Grant access to MCP tools](https://tailscale.com/docs/aperture/mcp-server\\#step-2-grant-access-to-mcp-tools)\r\n\r\nAperture is deny-by-default. Without MCP grants, users cannot access any MCP capabilities. Add MCP grants in the `grants` section of your configuration.\r\n\r\nMCP grants use the same `\"server/item\"` pattern as model grants, where the first segment is the server ID and the second is the item name. The following example grants all users access to all tools from the `local` server:\r\n\r\n```json\r\n{\r\n \"grants\": [\\\r\n {\\\r\n \"src\": [\"*\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/aperture\": [\\\r\n {\\\r\n \"mcp_tools\": \"local/*\"\\\r\n }\\\r\n ]\\\r\n }\\\r\n }\\\r\n ]\r\n}\r\n```\r\n\r\nThe following table describes the available MCP grant fields:\r\n\r\n| Field | Description | Example |\r\n| --- | --- | --- |\r\n| `mcp_tools` | Grant access to tools matching the pattern | `\"local/*\"` (all tools from `local` server) |\r\n| `mcp_resources` | Grant access to resources matching the pattern | `\"**\"` (all resources from all servers) |\r\n\r\nYou can use `*` to match any characters within a segment and `**` to match across segments. For example:\r\n\r\n- `\"local/search\"` matches the `search` tool from the `local` server.\r\n- `\"local/*\"` matches all tools from the `local` server.\r\n- `\"*/search\"` matches the `search` tool from any server.\r\n- `\"**\"` matches all items from all servers.\r\n\r\nAperture checks grants when clients list available tools and resources. Users only access the items they have permission for.\r\n\r\nRefer to the [grants configuration reference](https://tailscale.com/docs/aperture/configuration#grants) for the full grants syntax.\r\n\r\n### [Step 3: Connect an MCP client](https://tailscale.com/docs/aperture/mcp-server\\#step-3-connect-an-mcp-client)\r\n\r\nConfigure your MCP client (the AI agent host) to use the Aperture URL as the MCP server endpoint. For example, in an MCP client configuration file:\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"aperture\": {\r\n \"url\": \"http://ai/v1/mcp\"\r\n }\r\n }\r\n}\r\n```\r\n\r\nReplace `http://ai` with your Aperture hostname if you use a different [MagicDNS](https://tailscale.com/docs/features/magicdns) name.\r\n\r\nAperture automatically detects whether the client uses Streamable HTTP (the current MCP protocol) or legacy SSE and responds with the appropriate transport.\r\n\r\n### [Step 4: Verify the connection](https://tailscale.com/docs/aperture/mcp-server\\#step-4-verify-the-connection)\r\n\r\nConnect your MCP client to `http://ai/v1/mcp` and list available tools. The tool list should include prefixed names from all configured servers (for example, `local_search`, `remote_get_user`).\r\n\r\n## [Built-in tools](https://tailscale.com/docs/aperture/mcp-server\\#built-in-tools)\r\n\r\nAperture registers a built-in `internal_current_time` tool that returns the current date and time. This tool appears in `tools/list` responses alongside tools from configured remote servers. To grant access to it, use a grant pattern that matches the `internal` server, such as `\"internal/*\"`.\r\n\r\n## [Common scenarios](https://tailscale.com/docs/aperture/mcp-server\\#common-scenarios)\r\n\r\nThe following sections describe common tasks related to MCP server proxying.\r\n\r\n### [Enable dynamic registration](https://tailscale.com/docs/aperture/mcp-server\\#enable-dynamic-registration)\r\n\r\nDynamic registration lets MCP servers register themselves with Aperture at runtime instead of being configured statically. Set `accept_registrations` to `true` in the `mcp` section.\r\n\r\n```json\r\n{\r\n \"mcp\": {\r\n \"accept_registrations\": true,\r\n \"servers\": {}\r\n }\r\n}\r\n```\r\n\r\nWhen dynamic registration is enabled, remote servers register by sending a POST request to `/v1/mcp/register` with a JSON body containing their URL:\r\n\r\n```shell\r\ncurl -X POST http://ai/v1/mcp/register \\\r\n -H \"Content-Type: application/json\" \\\r\n -d '{\"url\": \"http://my-mcp-server:8080/v1/mcp\"}'\r\n```\r\n\r\nAperture performs an initial capability fetch from the registering server, then responds with HTTP 200 and begins polling the server for capability changes. Each dynamically registered server receives a sequential ID (`auto1`, `auto2`, and so on) and its tools are prefixed accordingly (for example, `auto1_search`).\r\n\r\nThe registration endpoint requires Tailscale authentication, the same as all other Aperture endpoints. The registering server must be accessible through the tailnet.\r\n\r\nThe registering server must keep the HTTP connection to `/v1/mcp/register` open. Aperture sends keepalive messages on this connection every second. When the server closes the connection, Aperture automatically unregisters all of its tools and resources.\r\n\r\nYou can combine static servers and dynamic registration in the same configuration. Static servers are always available, while dynamically registered servers come and go as they connect and disconnect.\r\n\r\n## [MCP configuration reference](https://tailscale.com/docs/aperture/mcp-server\\#mcp-configuration-reference)\r\n\r\nRefer to the [Aperture configuration reference](https://tailscale.com/docs/aperture/configuration#mcp) for the full `mcp` configuration syntax. The following sections describe how Aperture handles transport detection and server availability.\r\n\r\n### [Transport auto-detection](https://tailscale.com/docs/aperture/mcp-server\\#transport-auto-detection)\r\n\r\nAperture automatically detects whether each remote MCP server supports Streamable HTTP (the current protocol) or legacy SSE. When connecting to a remote server, Aperture tries Streamable HTTP first and falls back to SSE if the server does not support it. Remote servers can be upgraded to a later protocol version without restarting Aperture.\r\n\r\nThe same auto-detection applies to clients connecting to Aperture's `/v1/mcp` endpoint. Aperture serves both Streamable HTTP and legacy SSE clients.\r\n\r\n### [Capability polling](https://tailscale.com/docs/aperture/mcp-server\\#capability-polling)\r\n\r\nAperture polls each configured remote MCP server every 5 seconds to detect capability changes. When a remote server adds or removes tools or resources, Aperture automatically updates the registrations, making the changes visible to connected clients.\r\n\r\nIf a remote server becomes unavailable, Aperture unregisters all of its tools and resources until the server recovers. Polling continues in the background, and Aperture re-registers capabilities when the server comes back online.\r\n\r\n## [Limitations](https://tailscale.com/docs/aperture/mcp-server\\#limitations)\r\n\r\nMCP server proxying has the following limitations:\r\n\r\n- **Experimental feature**: The MCP configuration syntax and grants format might change in future releases.\r\n- **Polling-based discovery**: Aperture detects remote server capability changes through polling (every 5 seconds), not push notifications. There is a brief delay between a remote server adding a tool and that tool becoming available to clients.\r\n- **No per-tool authorization on calls**: Grants control which tools appear in the tool list. There is no separate authorization check at tool call time. A user who knows a tool's prefixed name can call it even without a matching grant, because grant enforcement applies to listing, not calling.\r\n\r\n## [Troubleshooting](https://tailscale.com/docs/aperture/mcp-server\\#troubleshooting)\r\n\r\nUse the following sections to diagnose and resolve common issues with MCP server configuration.\r\n\r\n### [MCP tools do not appear](https://tailscale.com/docs/aperture/mcp-server\\#mcp-tools-do-not-appear)\r\n\r\nIf tools from a configured MCP server are not visible:\r\n\r\n1. Verify the URL in your configuration is correct and the MCP server is running.\r\n2. Check that the MCP server is reachable from the Aperture host. Test with `curl -v ` from the Aperture host.\r\n3. Verify your grants include `mcp_tools` patterns that match the server and tool names. Without grants, users cannot access any MCP tools.\r\n\r\n### [Connection refused or host not found](https://tailscale.com/docs/aperture/mcp-server\\#connection-refused-or-host-not-found)\r\n\r\nThese errors indicate the MCP server URL is unreachable.\r\n\r\n- **Connection refused**: The server is not running or is not listening on the configured port.\r\n- **Host not found**: The hostname cannot be resolved. For tailnet hostnames, verify the MCP server device is connected to the tailnet and check with `tailscale status`.\r\n\r\n### [Tools appear and then disappear](https://tailscale.com/docs/aperture/mcp-server\\#tools-appear-and-then-disappear)\r\n\r\nIf tools are briefly visible and then become unavailable, the remote MCP server is likely crashing or restarting. Aperture automatically unregisters tools when a remote server becomes unreachable and re-registers them when the server recovers.\r\n\r\n### [Dynamic registration fails](https://tailscale.com/docs/aperture/mcp-server\\#dynamic-registration-fails)\r\n\r\nIf remote servers cannot register dynamically:\r\n\r\n1. Verify `accept_registrations` is set to `true` in your `mcp` configuration.\r\n2. Ensure the remote server sends a valid POST request to `/v1/mcp/register` with a JSON body containing `{\"url\": \"\"}`.\r\n3. The remote server must keep the HTTP connection open after registration. If the connection closes, Aperture unregisters the server's tools immediately.\r\n\r\n### [Tool calls time out](https://tailscale.com/docs/aperture/mcp-server\\#tool-calls-time-out)\r\n\r\nIf tool calls fail with timeout errors, the remote MCP server is taking too long to respond. Aperture retries tool calls once on connection errors. Check the remote server's performance and ensure it can respond within a reasonable time.\r\n\r\n![Project Logo](https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed)\r\n\r\nAsk AI\r\n\r\nreCAPTCHA\r\n\r\nRecaptcha requires verification.\r\n\r\nprotected by **reCAPTCHA**\r\n","html":"

MCP server proxying

\n

Last validated: Mar 30, 2026

\n

Aperture MCP server proxyingis currently in alpha.

\n

Aperture can aggregate tools and resources from multiple remote Model Context Protocol (MCP) servers and expose them to AI agents through a single /v1/mcp endpoint. This lets you centralize MCP tool management behind your Aperture proxy with the same identity-based access control used for LLM providers.

\n

Aperture acts as an MCP server when communicating with AI agent clients and as an MCP client when communicating with remote MCP servers. Clients connect to Aperture's /v1/mcp endpoint and access an aggregated view of all tools and resources from every configured remote server.

\n

Use cases

\n

MCP server proxying addresses the following use cases:

\n\n

Key MCP concepts

\n

The Model Context Protocol defines a standard way for AI agents to discover and use external capabilities. The following concepts are relevant to configuring MCP in Aperture:

\n\n

Prerequisites

\n

Before you can use MCP server proxying, you need the following:

\n\n

Get started

\n

To configure MCP server proxying in Aperture, add remote servers, grant users access to MCP tools, and connect an MCP client.

\n

Step 1: Configure MCP servers

\n

Open the Settings page of the Aperture dashboard and add an mcp section to your configuration with one or more remote servers.

\n
{\r\n  \"mcp\": {\r\n    \"servers\": {\r\n      \"local\": {\r\n        \"url\": \"http://localhost:8185/v1/mcp\"\r\n      },\r\n      \"remote\": {\r\n        \"url\": \"http://mcp-server.example.ts.net:8080/v1/mcp\"\r\n      }\r\n    }\r\n  }\r\n}\n
\n

Each key in the servers map is a server ID that Aperture uses as a name prefix. For the configuration above:

\n\n

Name prefixing prevents collisions when multiple servers expose tools with the same name. Clients receive the prefixed names and Aperture automatically strips the prefix when forwarding calls to the remote server.

\n

The Aperture host uses its tailnet HTTP client for connections to remote MCP servers, so you can use tailnet hostnames (for example, http://mcp-server.example.ts.net:8080/v1/mcp) without additional network configuration.

\n

Step 2: Grant access to MCP tools

\n

Aperture is deny-by-default. Without MCP grants, users cannot access any MCP capabilities. Add MCP grants in the grants section of your configuration.

\n

MCP grants use the same \"server/item\" pattern as model grants, where the first segment is the server ID and the second is the item name. The following example grants all users access to all tools from the local server:

\n
{\r\n  \"grants\": [\\\r\n    {\\\r\n      \"src\": [\"*\"],\\\r\n      \"app\": {\\\r\n        \"tailscale.com/cap/aperture\": [\\\r\n          {\\\r\n            \"mcp_tools\": \"local/*\"\\\r\n          }\\\r\n        ]\\\r\n      }\\\r\n    }\\\r\n  ]\r\n}\n
\n

The following table describes the available MCP grant fields:

\n

| Field | Description | Example |\r\n| --- | --- | --- |\r\n| mcp_tools | Grant access to tools matching the pattern | \"local/*\" (all tools from local server) |\r\n| mcp_resources | Grant access to resources matching the pattern | \"**\" (all resources from all servers) |

\n

You can use * to match any characters within a segment and ** to match across segments. For example:

\n\n

Aperture checks grants when clients list available tools and resources. Users only access the items they have permission for.

\n

Refer to the grants configuration reference for the full grants syntax.

\n

Step 3: Connect an MCP client

\n

Configure your MCP client (the AI agent host) to use the Aperture URL as the MCP server endpoint. For example, in an MCP client configuration file:

\n
{\r\n  \"mcpServers\": {\r\n    \"aperture\": {\r\n      \"url\": \"http://ai/v1/mcp\"\r\n    }\r\n  }\r\n}\n
\n

Replace http://ai with your Aperture hostname if you use a different MagicDNS name.

\n

Aperture automatically detects whether the client uses Streamable HTTP (the current MCP protocol) or legacy SSE and responds with the appropriate transport.

\n

Step 4: Verify the connection

\n

Connect your MCP client to http://ai/v1/mcp and list available tools. The tool list should include prefixed names from all configured servers (for example, local_search, remote_get_user).

\n

Built-in tools

\n

Aperture registers a built-in internal_current_time tool that returns the current date and time. This tool appears in tools/list responses alongside tools from configured remote servers. To grant access to it, use a grant pattern that matches the internal server, such as \"internal/*\".

\n

Common scenarios

\n

The following sections describe common tasks related to MCP server proxying.

\n

Enable dynamic registration

\n

Dynamic registration lets MCP servers register themselves with Aperture at runtime instead of being configured statically. Set accept_registrations to true in the mcp section.

\n
{\r\n  \"mcp\": {\r\n    \"accept_registrations\": true,\r\n    \"servers\": {}\r\n  }\r\n}\n
\n

When dynamic registration is enabled, remote servers register by sending a POST request to /v1/mcp/register with a JSON body containing their URL:

\n
curl -X POST http://ai/v1/mcp/register \\\r\n  -H \"Content-Type: application/json\" \\\r\n  -d '{\"url\": \"http://my-mcp-server:8080/v1/mcp\"}'\n
\n

Aperture performs an initial capability fetch from the registering server, then responds with HTTP 200 and begins polling the server for capability changes. Each dynamically registered server receives a sequential ID (auto1, auto2, and so on) and its tools are prefixed accordingly (for example, auto1_search).

\n

The registration endpoint requires Tailscale authentication, the same as all other Aperture endpoints. The registering server must be accessible through the tailnet.

\n

The registering server must keep the HTTP connection to /v1/mcp/register open. Aperture sends keepalive messages on this connection every second. When the server closes the connection, Aperture automatically unregisters all of its tools and resources.

\n

You can combine static servers and dynamic registration in the same configuration. Static servers are always available, while dynamically registered servers come and go as they connect and disconnect.

\n

MCP configuration reference

\n

Refer to the Aperture configuration reference for the full mcp configuration syntax. The following sections describe how Aperture handles transport detection and server availability.

\n

Transport auto-detection

\n

Aperture automatically detects whether each remote MCP server supports Streamable HTTP (the current protocol) or legacy SSE. When connecting to a remote server, Aperture tries Streamable HTTP first and falls back to SSE if the server does not support it. Remote servers can be upgraded to a later protocol version without restarting Aperture.

\n

The same auto-detection applies to clients connecting to Aperture's /v1/mcp endpoint. Aperture serves both Streamable HTTP and legacy SSE clients.

\n

Capability polling

\n

Aperture polls each configured remote MCP server every 5 seconds to detect capability changes. When a remote server adds or removes tools or resources, Aperture automatically updates the registrations, making the changes visible to connected clients.

\n

If a remote server becomes unavailable, Aperture unregisters all of its tools and resources until the server recovers. Polling continues in the background, and Aperture re-registers capabilities when the server comes back online.

\n

Limitations

\n

MCP server proxying has the following limitations:

\n\n

Troubleshooting

\n

Use the following sections to diagnose and resolve common issues with MCP server configuration.

\n

MCP tools do not appear

\n

If tools from a configured MCP server are not visible:

\n
    \n
  1. Verify the URL in your configuration is correct and the MCP server is running.
    2. \n
  2. Check that the MCP server is reachable from the Aperture host. Test with curl -v <your-mcp-server-url> from the Aperture host.
    3. \n
  3. Verify your grants include mcp_tools patterns that match the server and tool names. Without grants, users cannot access any MCP tools.
    4. \n
\n

Connection refused or host not found

\n

These errors indicate the MCP server URL is unreachable.

\n\n

Tools appear and then disappear

\n

If tools are briefly visible and then become unavailable, the remote MCP server is likely crashing or restarting. Aperture automatically unregisters tools when a remote server becomes unreachable and re-registers them when the server recovers.

\n

Dynamic registration fails

\n

If remote servers cannot register dynamically:

\n
    \n
  1. Verify accept_registrations is set to true in your mcp configuration.
    2. \n
  2. Ensure the remote server sends a valid POST request to /v1/mcp/register with a JSON body containing {\"url\": \"<MCP_SERVER_URL>\"}.
    3. \n
  3. The remote server must keep the HTTP connection open after registration. If the connection closes, Aperture unregisters the server's tools immediately.
    4. \n
\n

Tool calls time out

\n

If tool calls fail with timeout errors, the remote MCP server is taking too long to respond. Aperture retries tool calls once on connection errors. Check the remote server's performance and ensure it can respond within a reasonable time.

\n

\"Project

\n

Ask AI

\n

reCAPTCHA

\n

Recaptcha requires verification.

\n

protected by reCAPTCHA

\n"}