Tailnet MCP bridge

tailnet-mcp

tailnet 内の Streamable HTTP MCP サーバーにすべての通信を転送する、stdio MCP サーバーです。

ホスト型エージェント（Grok、クラウド型コーディングエージェント、サンドボックス化されたアシスタント）が MCP サーバーを利用する方法は、通常 2 つあります。URL 経由：ベンダーのサーバーが接続するため、サーバーをパブリックインターネット上に置く必要があります。コマンド経由：エージェントが自分のコンピューター上でプロセスを起動しますが、そのコンピューターは tailnet に参加しておらず、そこで tailscaled を実行することもできません（root 権限がなく、TUN も使えません）。tailnet-mcp はコマンド経由で動作します。Tailscale ノード（tsnet）を組み込み、タグ付きデバイスとして tailnet に参加して、stdio とサーバーの間を中継します。サーバーは tailscale serve の背後に置かれ、インターネットに公開されることはありません。

agent ──stdio──▶ tailnet-mcp (tag:agent) ══tailnet══▶ tailscale serve ──▶ MCP server on 127.0.0.1

インストール

Releases から linux または darwin、amd64 または arm64 向けの静的バイナリをダウンロードし、SHA256SUMS と照合してください。または、自分でビルドすることもできます。

CGO_ENABLED=0 go install github.com/zedong-peng/tailnet-mcp@latest

または、/home/nonroot/.local/state/tailnet-mcp にボリュームをマウントして、イメージ ghcr.io/zedong-peng/tailnet-mcp を実行します。MCP Registry にも io.github.zedong-peng/tailnet-mcp として登録されています。

使い方

1. 推測されにくいパスを使い、サーバーを tailnet 内だけに公開します。

   tailscale serve --bg --https=8443 --set-path=/$(openssl rand -hex 16) http://127.0.0.1:8080/mcp
   

2. エージェント用のタグを付けた、事前認証済みのワンタイム認証キーを作成し（管理コンソールまたは API）、エージェントのコンピューターから一度ログインします。

   TS_AUTHKEY=tskey-auth-... tailnet-mcp -hostname my-agent -url https://server.tailnet.ts.net:8443/<path> -check
   

   -check は接続して、サーバーのツールを stderr に出力して終了します。ノードキーは -state に保存されます（既定値は ~/.local/state/tailnet-mcp/<hostname>）。永続ストレージに保存してください。タグ付きノードは期限切れにならないため、キーを再度使う必要はありません。

3. キーを含めず、同じコマンドをエージェントの MCP サーバーとして登録します。

   tailnet-mcp -hostname my-agent -url https://server.tailnet.ts.net:8443/<path>
   

各プロセスはそれぞれ独立した tailnet ノードです。2 つ目のサーバーを使う場合は、別の -hostname を指定して 2 つ目のプロセスを実行してください。

セキュリティを強化する

エージェントは信頼できない入力（Web ページ、メール）を読み取るため、ツールで許可されていることなら何でも実行するよう仕向けられる可能性があると考えてください。エージェントの振る舞いに依存しない、次の 3 つの層で保護します。

• ネットワーク。 タグには必要なポートへの grant だけを与え、それ以外は許可しません。

  "grants": [
    {"src": ["tag:my-agent"], "dst": ["server"], "ip": ["tcp:8443"]},
  ],
  "tests": [
    {"src": "tag:my-agent", "accept": ["server:8443"], "deny": ["server:22", "server:443"]},
  ],
  

  すべてを許可する grant（"src": ["autogroup:member"], "dst": ["*"]）はタグ付きデバイスには適用されないため、そのタグが得られるのはこの grant だけです。

• パス。 tailscale serve --set-path は秘密のパスでのみ応答し、ポート上のほかのパスには 404 を返します。tailnet 内のほかのデバイスは、ポートを推測してもサーバーを利用できません。

• サーバー。 エージェント側ではなく、データが存在する場所で権限を強制します。たとえば、下書きの保存のみ可能なメールサーバーや、共有コレクション 1 つの閲覧専用メンバーとして設定されたパスワード保管庫アカウントです。examples/private-tools では、両方の設定例を紹介しています。

動作

• 最初のリクエストの前に、応答があるまでサーバーのノードに ping を送信します。再起動直後は、サーバーにノードへの古いパスが残っている場合があり、最初の接続がタイムアウトすることがあります。
• サーバーに到達しなかったリクエストのみ再試行するため、ツール呼び出しが二重に送信されることはありません。
• サーバーが再起動してセッションを忘れた場合（404、またはセッションに関する 400）、ブリッジは initialize を再送し、リクエストを再送信します。クライアント側では気付きません。
• リクエストに失敗すると、理由を含む JSON-RPC エラーが返されるため、クライアントが返ってこない応答を待ち続けることはありません。
• EOF を受信すると、DELETE でセッションを終了します。ログは stderr に出力され、stdout には MCP フレームのみが出力されます。-v を指定すると、tsnet 自身のログも出力されます。

未対応：サーバーが応答以外でメッセージを送信できるようにする、オプションの GET ストリームです。ほとんどのツールサーバーと同様に、サーバーは各リクエストに対して個別に応答します。

比較

• mcp-remote などの標準入出力と HTTP のブリッジでは、サーバーへのネットワーク経路が必要です。エージェントのサンドボックス内では、公開 URL が必要になります。
• サンドボックス内での tailscale up には、root 権限と TUN デバイスが必要です。タグ付きキーではなくユーザーとしてログインすると、サンドボックスからそのユーザーが tailnet 全体にアクセスできてしまいます。
• Tailscale Aperture はサーバー側のゲートウェイです。HTTP MCP サーバーを集約し、ユーザーごとにツールを付与します。サンドボックス化されたエージェントを tailnet に接続するものではないため、両者は併用できます。

ビルドとテスト

go test -race ./...
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" .

v* をタグ付けすると、4 つのバイナリ、イメージ、レジストリエントリーが公開されます。