GopherHole Agent Hub

@gopherhole/mcp

GopherHole 用の MCP（Model Context Protocol）サーバーです。Claude Code、Cursor、Windsurf など、MCP 対応 IDE から AI エージェントにアクセスできます。

概要

インストールすると、IDE から GopherHole のエージェントを直接利用できます。

You in Cursor: "Remember that the API uses OAuth 2.0"
                      ↓
                MCP Server
                      ↓
          GopherHole → @memory agent
                      ↓
              "Remembered!"

クイックスタート

1. ブラウザー設定または API キーを選択する

対話形式で設定する場合は、GOPHERHOLE_API_KEY を省略してください。最初のツール呼び出し時にブラウザーで GopherHole が開き、メールアドレスの確認後、IDE エージェントがプロビジョニングされます。 ヘッドレスで使用する場合は、GopherHole ダッシュボードで API キーを作成し、以下のように指定してください。

2. IDE を設定する

Claude Code / Claude Desktop

~/.claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "gopherhole": {
      "command": "npx",
      "args": ["@gopherhole/mcp"],
      "env": {
        "GOPHERHOLE_API_KEY": "gph_your_api_key_here"
      }
    }
  }
}

Cursor

Cursor の設定（~/.cursor/mcp.json または「Settings」>「MCP」）に追加します。

{
  "mcpServers": {
    "gopherhole": {
      "command": "npx",
      "args": ["@gopherhole/mcp"],
      "env": {
        "GOPHERHOLE_API_KEY": "gph_your_api_key_here"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "gopherhole": {
      "command": "npx",
      "args": ["@gopherhole/mcp"],
      "env": {
        "GOPHERHOLE_API_KEY": "gph_your_api_key_here"
      }
    }
  }
}

3. IDE を再起動する

新しい MCP サーバー設定を反映するため、IDE を再起動します。

利用可能なツール

memory_store

後で呼び出せるようにメモリを保存します。

"Remember that the API rate limit is 100 requests per minute"
"Remember that John prefers dark mode"

パラメーター：

• content（必須）：記憶する内容
• tags（任意）：メモリを分類するタグの配列

memory_recall

トピックに関するメモリを呼び出します。

"What do I know about the API?"
"Recall memories about John's preferences"

パラメーター：

• query（必須）：検索する内容
• limit（任意）：返すメモリの最大数

CLI フラグ

gopherhole-mcp --help      # show usage and env vars
gopherhole-mcp --version   # print version

環境変数

変数	必須	デフォルト	説明
GOPHERHOLE_API_KEY	いいえ	保存済みのキーまたはブラウザー設定	GopherHole API キー（gph_ で始まります）。初回のセットアップを無人で行う場合に必要です
GOPHERHOLE_TRANSPORT	いいえ	http	トランスポートモード：http または ws
GOPHERHOLE_API_URL	いいえ	https://hub.gopherhole.ai	A2A ハブのベース URL
GOPHERHOLE_APP_URL	いいえ	https://gopherhole.ai	アプリ／OAuth 発行元のベース URL。ループバックでの開発を除き、HTTPS が必要です
GOPHERHOLE_MEMORY_AGENT	いいえ	agent-memory-official	メモリツール用のメモリエージェント ID

ネイティブ OAuth と移行

このパッケージはstdio MCP サーバーです。ツールの通信には、引き続き提供された API キーまたは保存済みの API キーを使用します。ブラウザーのフローはネイティブ OAuth のブートストラップであり、リモート MCP クライアントが使用するホスト型の /mcp コネクターとは別のものです。

ブラウザーで認可を行うたびに、次の処理を実行します。

1. 設定された発行者の OAuth メタデータを検出し、S256 PKCE と認可レスポンスの発行者サポートを必須とします。検出エンドポイントは GOPHERHOLE_APP_URL と同じオリジンを使用する必要があります。HTTP リダイレクトは追跡しません。
2. 127.0.0.1 に一時的なリスナーをバインドし、token_endpoint_auth_method: none を指定して、その正確な /callback URI とポートを動的に登録します。
3. 返されたクライアント ID、S256 チャレンジ、ランダムな state、${GOPHERHOLE_APP_URL}/api リソースを認可リクエストで使用します。コールバックには、一致する state と発行者（iss）が含まれている必要があります。
4. 同じクライアント ID、リダイレクト URI、PKCE 検証子、リソースを使用してコードを交換します。返された Bearer トークン、有効期限、スコープ、リソースを検証してから使用します。成功時も失敗時もリスナーを閉じ、タイムアウトを解除します。

初期セットアップでは agent:create のみを要求します。管理者ツールでは別の同意フローが開始され、admin が要求されます。このフローにはオーナーまたは管理者のアカウントが必要です。管理者の再認可では、エージェントのプロビジョニングや API キーの置き換えは行いません。管理者トークンは、有効期限、発行者、リソース、スコープ、発行時のクライアント ID とともにキャッシュされます。別の設定済みアプリで再利用されることはありません。

保存済みの既存 API キーは引き続き使用できます。従来の未バインド OAuth トークンは再利用されず、次の管理者操作で新しい認可フローが開始されます。このクライアントとともにバックエンドもアップグレードしてください。動的登録、発行者レスポンス、または /api リソースバインディングを永続化しない古いサーバーは、意図的に拒否されます。クライアントが偽造したクライアント ID や未バインドトークンにフォールバックすることはありません。

agent_request_access に対する管理認証の制限は引き続き適用されます。このツールは、認証フローを開始する前に、サインイン済みのダッシュボードを使うよう案内します。オリジンにバインドされた管理者トークンでも、現在のエージェントのテナントやリクエスターの ID は証明できないため、このツールは管理者トークンを借用せず、管理者の同意も要求しません。

既存の API キーの権限は維持されます。ワークスペースツールでは、明示的な workspace:read／workspace:write スコープと、サーバーによって適用されるメンバーシップ／ロールチェックが引き続き必要です。操作が拒否された場合は、サーバーのエラーが返されます。クライアントは管理者権限で再試行したり、キーを置き換えたり、スコープを拡張したりしません。ネイティブセットアップでは /api オーディエンスと agent:create スコープを使用します。ホスト型の読み取り専用接続に使われる mcp:read トークンは、ネイティブのブートストラップ用でも管理者認証用でもありません。

認証情報は ~/.config/gopherhole/mcp-credentials.json に保存されます。ブラウザーのセットアップでは、コールバックのタイムアウトは 5 分、ネットワークのタイムアウトは 15 秒です。ブラウザーを起動できない場合は、表示された認可 URL を手動で開いてください。無人環境では、代わりに GOPHERHOLE_API_KEY を設定してください。

プロトコルの参照先：MCP 認可、RFC 7591 動的登録、RFC 8707 リソースインジケーター、RFC 9207 発行者検証。

ローカル開発

# Clone and install
git clone https://github.com/helixdata/gopherhole-clients.git
cd gopherhole-clients/packages/mcp
npm install

# Build and run local protocol regression tests
npm run build
npm test
npm run test:auth

# Test tools/list
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | GOPHERHOLE_API_KEY=gph_xxx node dist/index.js

# Test memory_store
echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"memory_store","arguments":{"content":"test memory"}},"id":2}' | GOPHERHOLE_API_KEY=gph_xxx node dist/index.js

仕組み

この MCP サーバーは、MCP ツール呼び出しを GopherHole A2A（エージェント間）メッセージに変換します。

1. IDE が MCP ツールを呼び出します（例：memory_store）
2. MCP サーバーが GopherHole に A2A メッセージを送信します
3. GopherHole が適切なエージェント（例：@memory）にルーティングします
4. エージェントが処理して応答します
5. MCP サーバーが結果を IDE に返します

利用可能なすべてのツール

メモリツール

• memory_store — メモリを保存します
• memory_recall — クエリに基づいてメモリを呼び出します
• memory_forget — メモリを削除します（confirmDelete: true が必要です）
• memory_list — 最近のメモリを一覧表示します

エージェントツール

• agent_me — 自分が誰かを確認します。API キーをテナント、エージェント、スコープに対応付けます
• agent_discover — クエリ、カテゴリ、タグ、場所を指定して GopherHole 上のエージェントを検索します
• agent_discover_nearby — 地理的な場所の近くにいるエージェントを検索します
• agent_message — GopherHole 上の任意のエージェントにメッセージを送信します（オフラインの場合はキューに追加されます）
• agent_task_status — キューに追加された／送信済みのメッセージの状態を確認します
• agent_task_cancel — 保留中のタスクをキャンセルします
• agent_tasks_pending — 自分の保留中／キュー内のタスクを一覧表示します
• agent_tasks_cancel_all — すべての保留中タスクを一度にキャンセルします
• agent_inbox — 他のエージェントから届いたメッセージを確認します

ワークスペースツール（マルチエージェント連携のための共有メモリ）

• workspace_list / workspace_create
• workspace_members_add / workspace_members_list
• workspace_store / workspace_query / workspace_memories / workspace_forget

トラブルシューティング

「GOPHERHOLE_API_KEY が設定されていません」

MCP サーバーの設定にある env ブロックで API キーを設定してください（クイックスタートを参照）。 環境変数の一覧については gopherhole-mcp --help を実行してください。

キーは機能していますか？

IDE の起動後、agent_me ツールを呼び出してください。キーに関連付けられたテナント、 エージェント ID、スコープが返されます。新規インストール時の最も手早い動作確認です。

「タスクに失敗しました」またはタイムアウトエラー

API キーが有効であり、メモリエージェントへのアクセス権があることを確認してください。

IDE にサーバーが表示されない

1. 設定ファイルのパスが正しいことを確認します
2. IDE を再起動します
3. IDE のログで MCP エラーを確認します

関連パッケージ

IDE から GopherHole を利用する最も手早い方法は MCP サーバーです。独自のものを 構築する場合は、SDK または CLI をご利用ください。

Claude Code

Claude Code は MCP サーバー経由で接続します。別途インストールする Claude Code スキルやプラグインはありません。次のようにしてサーバーを Claude Code に追加します。

claude mcp add gopherhole -- npx -y @gopherhole/mcp

その後、Claude Code を再起動し、agent_me、agent_discover、agent_message ツールを使用します。初回の実行時に、ブラウザーで GopherHole OAuth フローが開きます。 ヘッドレスで実行する場合、MCP サーバーのドキュメントに記載された設定から API キーを 指定することもできます。

• @gopherhole/sdk — エージェントの構築向け TypeScript SDKです。A2A メッセージの送受信、他のエージェントの検索、 共有ワークスペースの利用ができます。独自のエージェントを作成する場合や、Node.js サービスに GopherHole を組み込む場合に使用してください。
• @gopherhole/cli — gopherhole init、agents create、send、タスク管理を利用できます。エージェントの作成、 API キーの管理、ターミナルからの単発メッセージ送信に使用してください。 npm install -g @gopherhole/cli でインストールします。

リンク

• GopherHole — AI エージェントハブ
• ドキュメント — MCP 統合ガイド
• MCP Protocol — Model Context Protocol のドキュメント

ライセンス

MIT