tailscale -echo

This MCP server provides an identity-aware endpoint within your private Tailscale network. It leverages identity headers passed through to applications behind tailscale serve, allowing downstream tools and services to access information about the logged-in user (such as their email) when handling requests. The server is designed to work behind a Tailscale proxy and can be queried as an HTTP MCP server, enabling clients and tooling to interact with MCP endpoints while preserving user identity context.

To use it, connect to the MCP server endpoint over your Tailnet (for example: https://ts-mcp-echo.yourtailnetname.ts.net/mcp). If you have an MCP Client or integration that supports Streaming HTTP MCP servers, you can route requests through a proxy (such as mcp-remote) to reach the tailscale-backed endpoint. The README example shows a configuration that points Claude Desktop to the remote MCP via mcp-remote, enabling a greet-capable tool to respond with identity-aware information.

Prerequisites:

• Docker and Docker Compose installed on your machine
• A Tailnet API auth key (TS_AUTHKEY) from your Tailnet admin console
• Access to the repository or image that contains the MCP server setup

Installation steps:

1. Prepare your environment file with the Tailnet auth key:

# .env
TS_AUTHKEY=tskey-auth-your-key-here

2. Start the MCP server stack using Docker Compose, as described in the README. This typically spins up two containers: the MCP server and the tailscale serve proxy.

# From the project root (where docker-compose.yml is located)
docker compose up -d

3. Verify the containers are running:

docker ps

4. If you need to customize the image used by the MCP server, replace image-name in the docker run command with your specific image and rebuild as needed. Ensure the TS_AUTHKEY is accessible inside the container as an environment variable.

Tips:

• If you run into authentication issues, double-check TS_AUTHKEY and that it has the correct permissions in your Tailnet admin settings.
• Ensure the tailscale serve proxy container is healthy and reachable from the MCP server container.

Environment variables and configuration:

• TS_AUTHKEY is required to authorize with Tailnet; store it securely in a .env file and ensure it is mounted or passed to the container.
• If you modify the compose setup, ensure the MCP endpoint path remains /mcp and that DNS/SSL configuration allows external clients to resolve https://ts-mcp-echo.yourtailnetname.ts.net/mcp.
• The server is designed to expose identity headers to downstream applications, enabling identity-aware routing and access control in internal services.

Common issues:

• TLS/SSL certificate errors when accessing the MCP endpoint from clients outside the Tailnet – ensure proper cert propagation or use a valid DNS name inside the Tailnet.
• Logs showing missing identity headers – verify that the tailscale serve proxy is correctly configured to pass headers to the MCP server.
• If using Claude Desktop or other clients, ensure the proxy configuration (mcp-remote or equivalent) points to the correct MCP endpoint URL.