contextq-mcp

@contextq/mcp

ContextQ 用 MCP サーバーです。ContextQ のナレッジ管理 API（保存、検索、取り込み、目標グラフ、エージェントセッション、リレーなど、89 個のツール）を Model Context Protocol ツールとして公開します。tools/list のトークンコストを抑えるため、接続時には厳選された約 24 個のツールセットが読み込まれます。残りのツールはオンデマンドで読み込むか、CONTEXT_MCP_TOOL_PROFILE=full を設定して読み込みます。詳しくは以下をご覧ください。

npx -y @contextq/mcp

クライアントの設定

すべてのクライアントで、次の 2 つの環境変数が必要です。

変数	説明
CONTEXT_API_URL	ContextQ サーバーのベース URL（例：https://ctx.example.com）
CONTEXT_API_KEY	すべてのリクエストで Authorization: Bearer として送信される API キー

任意の設定：

変数	説明
CONTEXT_MCP_TOOL_PROFILE	default（未設定時のデフォルト）では、接続時に厳選された約 24 個のツールセットが読み込まれ、ほとんどのホストで余裕のあるツール一覧の上限を十分に下回ります。full では、最初から約 89 個すべてのツールが読み込まれます。default の場合、残りのツールは再接続せずに ctx_tool_groups（一覧表示）／ctx_load_tool_group（読み込み）ツールから利用できます。詳しくは docs/mcp-tools.md の「ToolSearch の延期時の検出可能性」をご覧ください。

セットアップ方法：Claude Code と Claude Desktop は、contextq init CLI コマンドで自動セットアップできます。Cursor、Windsurf、Cline では設定ファイルを手動で編集する必要があります。詳しくは docs/mcp-setup.md の完全なリファレンスをご覧ください。

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

Claude Code

claude mcp add contextq \
  -e CONTEXT_API_KEY=sk_live_YOUR_API_KEY \
  -e CONTEXT_API_URL=https://ctx.example.com \
  -- npx -y @contextq/mcp

Cursor

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

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

Windsurf

ステータス（2026-06-02）：Windsurf は Devin Desktop にリブランドされ、Cascade はサポート終了となりました（2026-07-01）。既存の Windsurf インストールをお使いの場合、以下の設定は引き続き適用されますが、新規インストールでは Devin Desktop を使用してください。Devin Desktop では、.devin/mcp.json で同じ MCP 設定形式を使用します。

Windsurf の MCP 設定（.windsurf/mcp.json）に追加します。

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      }
    }
  }
}

送信されるデータとテナントの分離

• エージェントが行ったリクエストのみが送信されます。 MCP サーバーはステートレスなプロキシです。各ツール呼び出しを CONTEXT_API_URL 経由で ContextQ API に転送し、レスポンスを返します。テレメトリやバックグラウンド同期はなく、使用状況の追跡も ContextQ サーバーのログに記録されるものに限られます。
• API キーはテナント単位です。 ContextQ の各 API キーは、単一のテナントに紐付けられています。すべての /api/* エンドポイントでテナント分離が適用されるため、API キーでアクセスできるのは、そのキーが発行されたテナントのみです。API レイヤーでテナント間のデータ漏えいが起こることはありません。
• リクエストごとに認証します。 CONTEXT_API_KEY は呼び出しごとに Authorization: Bearer ヘッダーとして送信されます。LLM に返されるツール名、引数スキーマ、レスポンスにこのキーが含まれることはありません。

クライアントのタイムアウト設定

ContextQ の一部のツールは、サーバー側で LLM の呼び出し、kNN スキャン、または大量の DB 操作を実行するため、通常の MCP クライアントのデフォルトのリクエストタイムアウトよりも長い時間がかかることがあります。サーバーが応答する前にクライアントが中断すると、ツールが壊れているように見えるタイムアウトエラーが発生しますが、通常はそうではありません。ツールが停止していると思い込まず、この MCP サーバーに対してサーバー単位のタイムアウトを長めに設定してください。

時間のかかるツール（ワークスペースのサイズに応じて、120000〜180000 ms などの長めのタイムアウトを推奨します）：

ツール	時間がかかる理由
ctx_dream	ベクトル類似度を使ってワークスペースのコンテキストをクラスタリングし、各クラスタに対して LLM による合成を 1 回ずつ実行します。
ctx_evolve	最大 20 件の最近傍コンテキストを対象に LLM による判定を実行し、リンクやアーカイブの要否を決定します。
ctx_ingest	ソースを取得・解析し、LLM によるクレーム抽出と kNN 差分検出を実行します。大規模な取り込みや URL をソースとする取り込みでは、すでに { jobId, statusUrl } が返され、ctx_ingest_status によるポーリングが想定されています。ただし、小規模なインライン取り込みは引き続き同期的に実行され、数秒かかることがあります。
ctx_regenerate_mocs	テナントのすべてのコンテキストを再クラスタリングし、各クラスタに対して LLM による合成を 1 回ずつ実行します（管理者スコープ）。
ctx_memory_review_run	古いコンテキストをサンプリングし、それぞれについて LLM に判定を求めます（スーパー管理者スコープ）。
ctx_bulk_update	1 回の呼び出しで最大 200 件のコンテキスト ID にライフサイクル／アーカイブのパッチを適用します。上限はありますが、1 行の更新より時間がかかります。
ctx_audit_cleanup_run	1 回の処理で最大 5000 件の activity_logs 行を削除します（スーパー管理者スコープ）。
ctx_snapshot_create / ctx_fork_world / ctx_diff_world	ワークスペースのメモリ状態全体（コンテキスト、リンク、目標グラフ）を複製または差分比較します。処理時間はワークスペースのサイズに応じて増加します。

その他のツール（ctx_search、ctx_get、ctx_save、ctx_list、agent_*、goal_*、relay_* など）は通常の CRUD／検索であり、デフォルトのクライアントタイムアウト内に十分完了するはずです。

これらの値は目安であり、保証ではありません。実際のレイテンシは、ContextQ サーバーのハードウェア、ワークスペースのサイズ、設定されている LLM／埋め込みプロバイダーによって異なります。タイムアウトを短く調整する前に、ご自身のデプロイ環境で計測してください。

.mcp.json のサーバー単位の request_timeout_ms

Claude Code を含む、.mcp.json に対応しているほとんどの MCP クライアントでは、サーバー上のすべてのツール呼び出しに対してクライアントのデフォルトのリクエストタイムアウトを上書きする、サーバー単位の request_timeout_ms を設定できます。

{
  "mcpServers": {
    "contextq": {
      "command": "npx",
      "args": ["-y", "@contextq/mcp"],
      "env": {
        "CONTEXT_API_KEY": "sk_live_YOUR_API_KEY",
        "CONTEXT_API_URL": "https://ctx.example.com"
      },
      "request_timeout_ms": 120000
    }
  }
}

request_timeout_ms はツール単位ではなくサーバー単位で適用されます。時間のかかるツールを定期的に呼び出す場合は、平均ではなく、呼び出す可能性のあるツールのうち最も時間がかかるものに合わせて値を設定してください。Claude Code 2.1.206 では、このフィールドが無視されて黙ってデフォルトの 60s が適用される不具合が修正されました。設定が反映されないように見える場合は、Claude Code のバージョンが 2.1.206 以上であることを確認してください。

Claude Code のアイドルタイムアウト

request_timeout_ms とは別に、Claude Code（2.1.187 以降）では CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT も適用されます。これはアイドル時の中断タイムアウト（デフォルトは約 5 分）で、MCP ツールの呼び出し中にその時間だけアクティビティがない場合に発動します。大規模なワークスペースに対して時間のかかるツールを呼び出す場合は、シェル環境（.mcp.json ではありません）に設定してください。

export CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=300000   # milliseconds; raise if ctx_dream/ctx_ingest still time out

どちらの設定も、個々の呼び出しにかかる時間の保証ではなく、推奨値として扱ってください。

API バージョンの互換性

この MCP サーバーが公開する 99 個のツールは、ContextQ API を直接反映したものです（デフォルトでは 24 個が読み込まれ、残りは CONTEXT_MCP_TOOL_PROFILE=full またはオンデマンドで利用できます。上記の「クライアントの設定」を参照してください）。ツール数やシグネチャはサーバーの変更に伴って変わります。互換性のあるバージョンを固定してください。

MCP パッケージ	ContextQ サーバー API
@contextq/[email protected]	ContextQ v2.x（99 個のツール）

ContextQ サーバーをアップグレードする際は、変更履歴を確認し、MCP パッケージを対応するメジャーバージョンに更新してください。バージョンが一致しないと、未知のツールが表示されたり、呼び出しシグネチャが機能しなくなったりすることがあります。

ライセンス

MIT