MCP Remote for Go

MCP Remote for Go

この Go 実装を使用すると、ローカル（stdio）接続のみをサポートする MCP クライアントから、認証に対応したリモート MCP サーバーへ接続できます。

概要

MCP Remote は、次の間をプロキシします。

• stdio トランスポートを使用するローカル MCP クライアント
• OAuth 認証を使用する Streamable HTTP または Server-Sent Events（SSE）対応のリモート MCP サーバー

機能

• Streamable HTTP トランスポート（MCP 2025-11-25） - セッション管理に対応した単一エンドポイントの POST/GET
• レガシー SSE トランスポート（MCP 2024-11-05） - 従来の 2 エンドポイント SSE 接続
• 自動ネゴシエーション - サーバーの機能を自動的に検出し、最適なトランスポートを選択します
• リクエストメタデータヘッダー（MCP 2026-07-28） - Mcp-Method と Mcp-Name は各メッセージから導出されます。ヘッダーで安全に使用できない値には、Base64 のセンチネルエンコーディングが使われます
• x-mcp-header のミラーリング（SEP-2243） - サーバーが指定したツール引数を Mcp-Param-* ヘッダーにコピーします。不正なアノテーションを持つツールは tools/list から除外されます
• ストリームクローズによるキャンセル（MCP 2026-07-28） - 最新のクライアントから notifications/cancelled を受け取ると、そのリクエストのレスポンスストリームを閉じます。これは、このリビジョンでキャンセルシグナルとして定義されている動作です
• PKCE を使用した OAuth 2.1（RFC 7636） - S256 コードチャレンジによる安全な認可
• トークンの自動更新（RFC 6749 §6） - アクセストークンの有効期限が近づくと、使用前に新しいトークンと交換します。また、サーバーに拒否された場合も再度交換するため、長時間実行するセッションでも、ブラウザーを再度開くことなくトークンの有効期限を超えて利用できます
• サーバーが通知するスコープとクライアント認証 - scope は WWW-Authenticate チャレンジ（RFC 6750 §3.1）または保護対象リソース自身の scopes_supported（RFC 9728 §2）から取得されます。また、トークンエンドポイントの認証方式は、クライアントが独自に選択した値ではなく、サーバーが公開する一覧から取得されます
• 一度に 1 つの認可 - 同じサーバーに対する並行プロキシはロックを介して連携します。そのため、2 つ目のインスタンスは同じアカウント用に別のブラウザーウィンドウを開くのではなく、1 つ目のインスタンスが取得したトークンを待ちます
• CSRF 保護付きコールバック - state によって各認可リクエストとそのコールバックを紐付け、RFC 9207 に従って発行者を検証し、ミックスアップ攻撃を防ぎます
• 保護対象リソースのメタデータ（RFC 9728） - リソースエンドポイントから認可サーバーを検出します。401 レスポンスで WWW-Authenticate を使った検出にも対応しています（§5.1）
• リソースインジケーター（RFC 8707） - MCP サーバーの正規 URI を、認可リクエストとトークンリクエストの両方で resource として送信します
• OAuth Discovery（RFC 8414）および OpenID Connect Discovery
• カスタムヘッダーと HTTPS の強制

プロトコルリビジョンのサポート

このプロキシは、ローカルの MCP クライアントが使用するリビジョンをそのまま転送し、クライアントに代わって選択することはありません。2025-11-25 以前のクライアントの場合は、従来どおり initialize ハンドシェイクを介して転送します。2026-07-28 のクライアントの場合は、各リクエストの _meta を、そのリビジョンで必要なルーティングヘッダーにミラーリングします。

そのため、両側が 2026-07-28 の前後で一致している必要があります。1 つの組み合わせを除き、すべての組み合わせが動作します。唯一の例外は、2026-07-28 より古いクライアントが、initialize ハンドシェイクを完全に廃止したサーバーと通信するケースです。仕様上、そのようなクライアントには先へ進むためのネゴシエーション手段がないため、両者を接続できるのは変換プロキシだけですが、これは意図的に対象外としています。このプロキシは自動ネゴシエーション中にこのケースを検出し、最初のツール呼び出しでエラーとして表面化させるのではなく、起動時に通知します。

公式 MCP SDK に対する検証内容については、test/conformance を参照してください。

インストール

デスクトップ拡張機能（MCPB）

お使いのプラットフォーム用の .mcpb ファイルをGitHub Releasesからダウンロードします。

プラットフォーム	ファイル
macOS（Apple Silicon）	mcp-remote-go-darwin-arm64.mcpb
macOS（Intel）	mcp-remote-go-darwin-amd64.mcpb
Windows（x64）	mcp-remote-go-windows-amd64.mcpb
Windows（ARM64）	mcp-remote-go-windows-arm64.mcpb

Claude Desktop で .mcpb ファイルを開いてインストールします。設定 UI が表示され、リモートサーバーの URL やその他のオプションを設定できます。

ソースからのビルド

# Clone the repository
git clone https://github.com/naotama2002/mcp-remote-go.git
cd mcp-remote-go

# Build the binary
make build

Docker の使用

Docker を使って mcp-remote-go を実行することもできます。一貫した環境を利用でき、デプロイも簡単になります。

GitHub Container Registry からプルする

# Pull the latest image
docker pull ghcr.io/naotama2002/mcp-remote-go:latest

# Or pull a specific version
docker pull ghcr.io/naotama2002/mcp-remote-go:{TAG}

ローカルでビルドする

# Build the Docker image
docker build -t mcp-remote-go .

使用方法

バイナリの使用方法

# Basic usage (auto-detects transport: tries Streamable HTTP first, falls back to SSE)
mcp-remote-go https://remote.mcp.server/mcp

# Force Streamable HTTP transport
mcp-remote-go https://remote.mcp.server/mcp --transport streamable-http

# Force legacy SSE transport
mcp-remote-go https://remote.mcp.server/sse --transport sse

# With custom port for OAuth callback
mcp-remote-go https://remote.mcp.server/mcp 9090

# With a custom header (useful for auth tokens, API keys, etc.)
mcp-remote-go https://remote.mcp.server/mcp --header "Authorization: Bearer YOUR_TOKEN"

# Multiple headers — repeat --header as many times as needed
# (Note: there is no --headers plural flag; `--header` takes one Name:Value at a time.)
mcp-remote-go https://remote.mcp.server/mcp \
  --header "Authorization: Bearer YOUR_TOKEN" \
  --header "X-API-Key: secret" \
  --header "X-Tenant-Id: acme"

# Allow HTTP for trusted networks (normally HTTPS is required)
mcp-remote-go http://internal.mcp.server/mcp --allow-http

# Via HTTP/HTTPS proxy
mcp-remote-go https://remote.mcp.server/mcp --https-proxy http://proxy.example.com:8080

Docker の使用方法

# Basic usage with Docker (auto-detects transport)
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

# Force Streamable HTTP transport
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp --transport streamable-http

# Force legacy SSE transport
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse --transport sse

# With custom port for OAuth callback
docker run --rm -it -p 9090:9090 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp 9090

# With custom headers
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp --header "Authorization: Bearer YOUR_TOKEN"

# Allow HTTP for trusted networks
docker run --rm -it -p 3334:3334 ghcr.io/naotama2002/mcp-remote-go:latest http://internal.mcp.server/mcp --allow-http

# Mount auth directory to persist OAuth tokens
docker run --rm -it -p 3334:3334 -v ~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

MCP クライアントの設定

デフォルトでは、mcp-remote-go はトランスポート（Streamable HTTP または SSE）を自動検出します。--transport フラグを指定すると、特定のトランスポートを強制できます。

検出時には server/discover リクエストを送信し、応答を読み取ります。このリクエストに応答するサーバーは 2026-07-28 以降のもので、応答にはサポートするすべてのリビジョンも示されます。JSON-RPC でリクエストを拒否するサーバーは、それより前のリビジョンですが、引き続き Streamable HTTP を使用します。POST にまったく応答しないサーバーは、非推奨の SSE トランスポートで提供されています。サーバーが initialize ハンドシェイクを完全に廃止していることが判明した場合、2026-07-28 より前の MCP クライアントでは接続する方法がないため、プロキシは起動時に警告をログに出力します。

Claude Desktop（MCPB 拡張機能）

Claude Desktop で最も簡単に使う方法は、.mcpb 拡張機能を利用することです。インストール後、GUI から設定します。

設定	説明	デフォルト
リモート MCP サーバー URL	リモートサーバーの URL（必須）	—
トランスポートモード	auto、streamable-http、または sse	auto
OAuth コールバックポート	OAuth コールバック用のローカルポート	3334
HTTP を許可	安全でない HTTP 接続を許可	false
HTTP/HTTPS プロキシ	プロキシサーバーの URL（例：http://proxy:8080）	—
Authorization ヘッダーの値	値の部分のみ — Authorization: は前に付けないでください。例：Bearer eyJhbGc...、Basic dXNlcjpwYXNz	—
カスタムヘッダー 1～5 — Name / Value	最大 5 個の追加ヘッダーを、Name/Value のフィールドペアごとに 1 つ設定します。ヘッダー名（例：X-API-Key）は Name フィールドに入力します。設定済みのヘッダーを確認できるよう、名前は表示されたままになります。Value フィールドには値を入力します。値は暗号化され、マスクされて保存されます。行をスキップするには Name を空欄にします。Authorization は上のフィールドに入力します。	—

形式に関する注意

プロキシの起動方法に応じて、同じ値を 3 通りの方法で入力できます。それぞれで形式が少し異なります。

場所	Authorization ヘッダー	その他のヘッダー
MCPB UI（上記）	Authorization Header Value フィールド — 値のみ（Bearer xxx）	Custom Header N のフィールドペア — 名前と値を別々のフィールドに入力
CLI --header（フラグを繰り返す）	--header "Authorization: Bearer xxx"	--header "X-API-Key: secret"
環境変数	MCP_AUTH_HEADER="Bearer xxx"（値のみ）	MCP_HEADERS — 1 行ごとに Name: Value を改行区切りで指定（以下の例を参照）

--headers（複数形）フラグはありません。 各ヘッダーを --header "Name: Value" として渡してください。複数のヘッダーを指定する場合は、フラグを繰り返します。

MCP_HEADERS にすでに Authorization: の行が含まれている場合、重複を避けるため MCP_AUTH_HEADER は無視されます。

各種コンテキストでの MCP_HEADERS の記述方法

1 つの環境変数の値に改行を埋め込む方法は、ツールごとに異なります。以下はいずれも同じ 2 つのヘッダー（X-API-Key: secret と X-Tenant: acme）を設定します。

# bash / zsh — $'...' is ANSI-C quoting that turns \n into a real newline
export MCP_HEADERS=$'X-API-Key: secret\nX-Tenant: acme'

# Portable shell — leave the double quotes open across a real newline
export MCP_HEADERS="X-API-Key: secret
X-Tenant: acme"

// Claude Desktop manual config — JSON \n is interpreted as a real newline
{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": ["https://remote.mcp.server/mcp"],
      "env": {
        "MCP_HEADERS": "X-API-Key: secret\nX-Tenant: acme"
      }
    }
  }
}

# docker-compose — YAML block scalar (|) preserves newlines
services:
  mcp-remote:
    image: ghcr.io/naotama2002/mcp-remote-go:latest
    environment:
      MCP_HEADERS: |
        X-API-Key: secret
        X-Tenant: acme

# docker run — same $'...' trick as bash/zsh
docker run --rm -it \
  -e MCP_HEADERS=$'X-API-Key: secret\nX-Tenant: acme' \
  ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/mcp

:: Windows CMD — double quotes don't expand \n, so use the literal escape
::               and the proxy will interpret it (see "Escape fallback" below).
set MCP_HEADERS=X-API-Key: secret\nX-Tenant: acme

# Windows PowerShell — backtick-n is the PowerShell newline escape
$env:MCP_HEADERS = "X-API-Key: secret`nX-Tenant: acme"

MCPB UI では MCP_HEADERS を使用しません。各 Custom Header N の Name/Value ペアは個別にプロキシへ渡されるため、区切り文字は必要ありません。

エスケープフォールバック（リテラルの \n）

バイナリに渡された値に実際の改行が含まれていない場合、プロキシはリテラルの2文字の並び \n（バックスラッシュ＋n）を区切り文字として解釈します。これは、実際の改行を埋め込めない環境（Windows CMD や通常の二重引用符を使うシェルなど）に対応します。実際の改行が含まれている場合、リテラルの \n はそのまま保持されるため、正当に \n を含むヘッダー値が変更されずに維持されます。

空行と : を含まない行は無視されます（後者は警告がログに記録されます）。そのため、ある項目に誤記があっても、ほかの項目が妨げられることはありません。

Claude Desktop（手動設定）

次の設定ファイルを編集します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

バイナリを使用する場合

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Docker を使用する場合

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Docker で OAuth トークンを永続化する場合：

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "-v",
        "~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Cursor

設定ファイル ~/.cursor/mcp.json を編集します。

バイナリを使用する場合

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Docker を使用する場合

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Windsurf

設定ファイル ~/.codeium/windsurf/mcp_config.json を編集します。

バイナリを使用する場合

{
  "mcpServers": {
    "remote-example": {
      "command": "/path/to/mcp-remote-go",
      "args": [
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

Docker を使用する場合

{
  "mcpServers": {
    "remote-example": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--net=host",
        "ghcr.io/naotama2002/mcp-remote-go:latest",
        "https://remote.mcp.server/mcp"
      ]
    }
  }
}

環境変数

すべてのオプションは環境変数でも設定できます。両方が設定されている場合は、CLI フラグが優先されます。

変数	説明	対応するフラグ
MCP_SERVER_URL	リモート MCP サーバーの URL	--server
MCP_TRANSPORT	トランスポートモード（auto、streamable-http、sse）	--transport
MCP_PORT	OAuth コールバックポート	--port
MCP_ALLOW_HTTP	HTTP を許可する場合は true に設定	--allow-http
MCP_HTTPS_PROXY	HTTP/HTTPS プロキシ URL	--https-proxy
MCP_AUTH_HEADER	認証ヘッダーの値のみ（例：Bearer xxx）。プロキシが自動的に Authorization: を付加します	--header "Authorization: ..."
MCP_HEADERS	任意のヘッダーを指定する、改行区切りの Name: Value リスト（例：X-API-Key: secret）	項目ごとに --header "Name: Value" を1つ指定

これらの環境変数は、GUI で設定した値をバイナリに渡すために、MCPB 拡張機能によって内部的に使用されます。

認証

認証が必要なサーバーに初めて接続するとき、アクセスを認可するためにブラウザーで URL を開くよう求められます。プログラムは OAuth フローが完了するまで待機し、その後接続を確立します。OAuth 認証のコールバックポートが使用中の場合は、自動的に利用可能なポートが使用されます。

OAuth の実装では、次をサポートしています。

• セキュリティを強化する、S256 コードチャレンジを使用したPKCE（RFC 7636）
• 認可サーバーを検出するための保護されたリソースメタデータ（RFC 9728）。401 時の WWW-Authenticate に基づく PRM 検索を含みます（§5.1）
• リソースインジケーター（RFC 8707） — MCP 認可仕様の要件に従い、認可リクエストとトークンリクエストの両方で、MCP サーバーの正規 URI が resource として送信されます
• **OAuth 2.0 認可サーバーメタデータ（RFC 8414）**および OpenID Connect Discovery

認可トークンは ~/.mcp-remote-go-auth/ に保存され、今後の接続で再利用されます。

トラブルシューティング

認証データを消去する

認証で問題が発生した場合は、保存されたデータを消去できます。

rm -rf ~/.mcp-remote-go-auth

VPN／証明書の問題

VPN の背後で証明書の問題が発生する場合は、CA 証明書を指定する必要があることがあります。

export SSL_CERT_FILE=/path/to/ca-certificates.crt
mcp-remote-go https://remote.mcp.server/sse

Docker の問題

ポートがすでに使用中

「ポートがすでに使用中」というエラーが表示された場合は、競合するサービスを停止するか、別のポートを使用してください。

# Use a different port
docker run --rm -it -p 3335:3334 ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

ボリュームマウント時の権限の問題

認証ディレクトリのマウント時に権限の問題が発生する場合：

# Make sure the directory exists and has proper permissions
mkdir -p ~/.mcp-remote-go-auth
chmod 755 ~/.mcp-remote-go-auth

# Run with volume mount
docker run --rm -it -p 3334:3334 -v ~/.mcp-remote-go-auth:/home/appuser/.mcp-remote-go-auth ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

MCP クライアントのネットワークの問題

MCP クライアントが Docker コンテナに接続できない場合は、ホストネットワークを使用してみてください。

# Use host networking mode
docker run --rm -i --net=host ghcr.io/naotama2002/mcp-remote-go:latest https://remote.mcp.server/sse

ライセンス

MIT