Zihin

@zihin/mcp-server

Zihin.ai プラットフォーム向けの stdio-to-HTTP MCP プロキシです。MCP クライアントを HTTP 経由で Zihin MCP Server に接続します。

Cliente MCP <-stdio-> [@zihin/mcp-server] <-HTTP-> https://llm.zihin.ai/mcp

クイックスタート

macOS / Linux：

ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server

Windows（PowerShell）：

$env:ZIHIN_API_KEY="zhn_live_xxx"; npx @zihin/mcp-server

実際には、ほとんどの MCP クライアント（Claude Desktop、Cursor など）では、設定の "env" ブロックを使って変数が自動的に設定されるため、シェルで手動設定する必要はありません。

設定

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

Claude Code

プロジェクトの .mcp.json に追加します：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

または CLI 経由で設定します（変数 ZIHIN_API_KEY をシェルで設定しておく必要があります）：

claude mcp add zihin -e ZIHIN_API_KEY=zhn_live_xxx -- npx -y @zihin/mcp-server

Cursor

ワンクリックでインストールします（ブラウザーのアドレスバーに貼り付けるか、open '<link>' を実行します）：

cursor://anysphere.cursor-deeplink/mcp/install?name=zihin&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6aWhpbi9tY3Atc2VydmVyIl0sImVudiI6eyJaSUhJTl9BUElfS0VZIjoiemhuX2xpdmVfeHh4In19

インストール後、MCP の設定で zhn_live_xxx を自分のキーに置き換えてください。または .cursor/mcp.json に追加します：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

VS Code（Copilot）

ボタンをクリックすると、設定済みの状態で VS Code が開きます（zhn_live_xxx を自分のキーに置き換えてください）。手動で設定する場合は、コマンド MCP: Add Server または .vscode/mcp.json を使用します：

{
  "servers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": { "ZIHIN_API_KEY": "zhn_live_xxx" }
    }
  }
}

Windsurf

~/.windsurf/mcp.json に追加します：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

Gemini CLI

gemini extensions install https://github.com/zihin-ai/gemini-cli-zihin

拡張機能のインストール時に API Key の入力を求められます（キーチェーンに保存されます）。MCP とコンテキストがインストールされます。手動で設定する場合は、「その他の MCP クライアント」を参照してください。

Codex（OpenAI）

~/.codex/config.toml（またはプロジェクト内の .codex/config.toml）に追加します：

[mcp_servers.zihin]
command = "npx"
args = ["-y", "@zihin/mcp-server"]
env_vars = ["ZIHIN_API_KEY"]

変数 ZIHIN_API_KEY をシェルで設定しておく必要があります。代わりに、インラインで設定することもできます：

[mcp_servers.zihin]
command = "npx"
args = ["-y", "@zihin/mcp-server"]

[mcp_servers.zihin.env]
ZIHIN_API_KEY = "zhn_live_xxx"

その他の MCP クライアント

stdio 経由で MCP プロトコルをサポートするクライアントであれば、このパッケージを使用できます。設定方法は共通です。ZIHIN_API_KEY 変数を設定した状態で npx -y @zihin/mcp-server を実行します。

環境変数

変数	必須	説明
ZIHIN_API_KEY	はい	テナントの API Key（形式は zhn_live_*、zhn_test_*、または zhn_dev_*）
ZIHIN_MCP_URL	いいえ	MCP Server の URL（デフォルト：https://llm.zihin.ai/mcp）
ZIHIN_MCP_CALL_TIMEOUT_MS	いいえ	tools/call のタイムアウト上限（ミリ秒単位。デフォルト：300000、5 分。許容範囲：1000～1800000）。サーバーにはチャネルごとの独自の期限があります（チャットはデフォルトで 150 秒、builder は 180 秒、その他のチャネルは 240 秒。いずれもサーバーの運用上の上限に従います）。デフォルト値を使うと、プロキシが接続を切る前にサーバーが診断可能なエラーを返せます。2026.10.5 のバックエンドスキルでは、chat_with_agent を含む外部チャネルの運用上の上限が 180 秒とされています。この値はサーバーの設定によって異なります。約 300 秒を超えると、Node の fetch（undici）が先に接続を切る場合があり、ヘッダーまたは本文に独自のタイムアウトが適用されます。

仕組み

このパッケージは、ローカルの MCP クライアント（stdio 経由）と Zihin MCP Server（HTTP 経由）の間で透過的なプロキシとして動作します：

• すべてのツール、リソース、プロンプトがサーバーから自動的に検出されます
• 認証、RBAC、テナントの分離は、API Key を介してサーバー側で適用されます
• ロール（admin/editor/member）は API Key によって決まります

Skills — IDE を Zihin に特化させる

サーバーは、エージェント、ツール、トリガー、診断、ガバナンスの作成に関する手順書である6つのスキルを、リソースを参照できるロール向けに zihin://skills/* として公開します（「Capabilities」を参照）。インストールは不要ですが、スキルの本文は自動では提供されません。クライアント（またはモデル）が resources/read で取得する必要があります。

クライアントのネイティブ形式でもインストールする場合（コンテキストに応じた自動有効化）：

# Claude Code (Agent Skills em .claude/skills/)
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client claude

# Cursor (.cursor/rules/*.mdc) | Windsurf (.windsurf/rules/) | Codex (AGENTS.md + .zihin/skills/)
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client cursor
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client all

# Offline (usa as skills empacotadas no npm)
npx @zihin/mcp-server install-skills --client claude --bundled

オプション：--client claude|cursor|windsurf|codex|all · --dir <raiz-do-projeto> · --global（claude のみ。~/.claude/skills にインストール） · --bundled（オフライン）。

スキルは稼働中のサーバーから取得されます（常に最新です）。取得に失敗した場合（ネットワーク障害、サーバー停止、キーの拒否）、または結果が空だった場合、コマンドは npm に同梱されたコピーをインストールします。これは --bundled と同じ内容で、リリース時点の状態に固定されています。失敗時には警告が表示されます。いずれの場合も、出力に使用したソース（fonte: server または fonte: bundled）が示されます。ZIHIN_API_KEY がなく、--bundled も指定されていない場合、フォールバックは行われず、コマンドはエラーで終了します。Codex では、スキルのインデックスを含む管理ブロックが AGENTS.md に挿入されます（`` の間に挿入。冪等）。スキルは .zihin/skills/ に配置されます。

Claude Code プラグイン（MCP + スキルを1つのコマンドで）

claude plugin marketplace add zihin-ai/zihin-mcp
claude plugin install zihin@zihin

このプラグインは、MCP サーバー（このパッケージ経由）と6つのスキルをインストールします。環境で ZIHIN_API_KEY がエクスポートされている必要があります。

Capabilities

利用可能な機能は、サーバー側で制御される API Key のロールによって異なります。

Role	Tools	Resources	Prompts
admin	すべて（88）	19	3
editor	読み取り（48 — 書き込みは一覧に表示されません）	19	3
member	コンシューマー向けサブセット（5）	-	-

本番環境で 04/10/2026 に確認した件数です（88 tools / 19 resources — 3つのカタログ + 10のスキーマ + 6つのスキル / 3 prompts）。サーバーの進化に伴い、正確な件数は変わる場合があります。

利用可能な Resources

URI	説明
zihin://agents	テナントのエージェント一覧
zihin://models	利用可能な LLM モデルのカタログ
zihin://schema-templates	設定用のスキーマテンプレート
zihin://schemas/{tipo}	各ペイロードの正式な契約（JSON Schema）— サーバーが検証するものと同一（10種類）
zihin://skills/{slug}	手順書（6つのスキル — 上記「Skills」セクションを参照）

利用可能な Prompts

名前	説明
setup-agent	エージェント全体を作成します（エージェント + ペルソナ + ツール + 公開）
add-tool	既存のエージェントにツールを追加します
configure-webhook	エージェントの webhook トリガーを設定します

テスト

87件のテスト：オフラインの単体テスト（エラー分類、タイムアウト上限、install-skills、レジストリ検証、プラグインマニフェストの整合性）と、本番サーバーに対する実際の統合テストです。ZIHIN_API_KEY がない場合はオフラインテストのみ実行されます。キーがある場合は、テストスイート全体を実行します。

ZIHIN_API_KEY=zhn_live_xxx npm test

カバレッジ：API Key の検証、ツール（セッショントラッキング、継続性、出力契約 — execution_id、cancelled、tools_used／tool_calls を含む chat_with_agent など）、リソース、プロンプト、MCP プロトコル（ミラーリングされたアイデンティティ + instructions）、エラー分類（SDK v1 および v2 の形式）、およびサーバーの期限に照らして確認する tools/call の上限です。

統合テストスイートは chat_with_agent を実際に2回呼び出します（セッション開始と継続）。エージェントの2ターン分が実行され、テナントには LLM の実費が発生します。CI では v* タグのワークフローでのみ実行されます。

トラブルシューティング

「ERRO: ZIHIN_API_KEY nao definida」

実行前に環境変数を設定してください。

# macOS / Linux
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server

# Windows (PowerShell)
$env:ZIHIN_API_KEY="zhn_live_xxx"; npx @zihin/mcp-server

「サーバーへの接続に失敗しました」

• インターネット接続を確認してください
• API Key が有効で、アクティブであることを確認してください
• カスタム URL を使用している場合は、ZIHIN_MCP_URL を確認してください

「ERRO FATAL: API Key invalida ou revogada」

API Key が Zihin のパネルで取り消されたか、無効化されています。新しいキーを生成し、MCP クライアントの設定を更新してください。変更後にプロセスを再起動してください。

「ツール X がプロキシの 300 秒の上限を超えたため、中止されました」

プロキシが tools/call を待機する時間は最大 5 分です。このメッセージが表示された場合、超過したのはサーバーの上限ではなく、プロキシの上限です。処理はサーバー上でキャンセルされています（2026-07-28 のダイアレクトでは、リクエストの中止がキャンセルシグナルになります）。そのため、トークンを消費し続ける孤立した実行はありません。

• 正当に時間のかかるエージェントのターンの場合：ZIHIN_MCP_CALL_TIMEOUT_MS（ミリ秒単位、範囲は 1000–1800000）で上限を引き上げてください。約 300 秒を超えると、Node の fetch 自体が先に中断する場合があります。
• サーバーが先にタイムアウトした場合（チャネルごとの期限：チャットのデフォルトは 150 秒、ビルダーは 180 秒、その他のチャネルは 240 秒。いずれもサーバーの運用上の上限に従います）：届くメッセージは別のもので、execution_id と session_id を含む TURN_TIMEOUT エラーです。この 2 つの識別子はサーバー上の実行との照合に使われるため、サポートにお知らせください。
• MCP クライアントには、これとは別の独自のタイムアウトがあります。ホストが先に処理を中断した場合、ホスト側のエラーが表示されます。

ツールがクライアントに表示されない

• 設定を変更した後、MCP クライアントを再起動してください
• Claude Desktop：~/Library/Logs/Claude/mcp*.log（macOS）または %APPDATA%\Claude\logs\mcp*.log（Windows）のログを確認してください

制限事項

• ターンには時間の上限があります：tools/call がプロキシで待機する時間は最大 5 分です（設定可能です。ZIHIN_MCP_CALL_TIMEOUT_MS を参照）。また、サーバーにもチャネルごとの期限があります（チャットのデフォルトは 150 秒、ビルダーは 180 秒、その他のチャネルは 240 秒。いずれもサーバーの運用上の上限に従います）。これを超えるターンはキャンセルされ、キューには追加されません。
• ストリーミング：chat_with_agent ツールは応答をまとめて返します（同期処理）。MCP プロトコルでは、ツールは完全な CallToolResult を返すと定義されており、段階的なストリーミングには対応していません。エージェントの実行中にリアルタイムでフィードバックを得るには、REST SSE エンドポイント（POST /api/v2/agents/:agent_id/stream）を使用してください。

要件

• Node.js >= 20
• macOS、Linux、Windows に対応

ライセンス

MIT