solucortex-mcp

SoluCortex MCP

SoluCortex — AI エージェントのための、常に更新される技術ナレッジ — の公式 Model Context Protocol サーバーです。

MCP 互換のエージェント（Claude Code、Claude Desktop、Cursor、Codex、Cline、…）を SoluCortex プロジェクトに接続すると、作業前に重要な決定、規約、リスク、アーキテクチャを想起し、 作業完了時には学んだことを記憶できます。

ウェブサイト： solucortex.ai · セットアップガイド： solucortex.ai/docs/mcp · ツールのリファレンス： solucortex.ai/docs/mcp-tools · PyPI： solucortex-mcp · MCP Registry： io.github.soluai-spa/solucortex-mcp

ツール

ツール	機能	使用するタイミング
solucortex_recall	タスクのための常に更新されるコンテキストを作成します（意味的類似度と重要度に基づいてランク付け）	コードに触れる前、タスクの開始時
solucortex_search	プロジェクトのメモリーを対象にした、オンデマンドの意味検索	タスクの途中で具体的な質問があるとき
solucortex_remember	メモリーを記録します（approved として保存され、認証済みエージェントとして記録されます）	完了時、または関連する技術的決定があったとき
solucortex_update_memory	既存のメモリーを修正します — 編集後は保留状態に戻り、パネルで人間による再承認が必要です	メモリーの趣旨は正しいものの、詳細が誤っているとき
solucortex_flag_memory	理由を添えて、メモリーに古い情報または誤りがあることを報告します。人間がパネルで対応します	メモリーの確認、アーカイブ、削除が必要なとき
solucortex_list_memories	意味検索を行わずにメモリーを一覧表示します	すばやく確認・監査するとき

設計によるガバナンス： エージェントが提案し、人間が管理します。エージェントはメモリーの status を変更したり、メタデータを書き換えたり、削除したりすることはできません。編集すると保留状態に戻り、 削除は SoluCortex パネルからのみ実行できます。

要件

• SoluCortex アカウントとプロジェクト API キー（プレフィックス scx_）が必要です。キーは SoluCortex ダッシュボードから取得できます。
• uv（推奨）、Python ≥ 3.10、Docker のいずれか。

設定

stdio モード（デフォルト、ローカル）

サーバーは環境変数のみで設定します。

変数	必須	説明
SOLUCORTEX_API_KEY	✅	プロジェクト API キー（scx_…）
SOLUCORTEX_PROJECT_ID	任意	デフォルトのプロジェクト UUID。省略した場合、バックエンドが API キーから推定します
SOLUCORTEX_URL	任意	API のベース URL。デフォルトは https://solucortex.ai

HTTP モード（リモート、マルチテナント）

MCP_TRANSPORT=http（または --http）を指定して実行すると、$PORT（デフォルトは 8080）で Streamable HTTP を提供します。これは https://mcp.solucortex.ai で使用されているモードです。認証情報は各リクエストに含め、環境変数は無視されます。

ヘッダー	必須	説明
Authorization: Bearer scx_…	✅	呼び出し元のプロジェクト API キー（指定しない場合は 401）
X-Solucortex-Project	任意	デフォルトのプロジェクト UUID。省略すると、バックエンドが API キーから推測します

GET /health（ローカルでは /healthz も）は認証なしで応答します（Cloud Run のフロントエンドは /healthz をインターセプトします）。MCP エンドポイントは /mcp で、ステートレスに動作し、リクエストやテナント間でデータを共有しません。

API キーをコミットしないでください。MCP クライアント設定の env ブロックか、ローカルの .env に保存してください（.env.example を参照）。

インストール

リモート（推奨 — インストール不要）

ホストされているサーバー https://mcp.solucortex.ai/mcp は Streamable HTTP に対応しており、キーは各リクエストに含まれます。

claude mcp add --transport http solucortex https://mcp.solucortex.ai/mcp \
  --header "Authorization: Bearer scx_xxx" \
  --header "X-Solucortex-Project: your-project-uuid"

または、リモート MCP に対応した任意のクライアントで使用できます。

{
  "mcpServers": {
    "solucortex": {
      "type": "http",
      "url": "https://mcp.solucortex.ai/mcp",
      "headers": {
        "Authorization": "Bearer scx_xxx",
        "X-Solucortex-Project": "your-project-uuid"
      }
    }
  }
}

Claude Code（ローカル、stdio）

claude mcp add solucortex \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  -- uvx solucortex-mcp

Claude Desktop / Cursor / Cline（JSON 設定）

クライアントの MCP 設定（claude_desktop_config.json、Cursor の mcp.json など）に追加します。

{
  "mcpServers": {
    "solucortex": {
      "command": "uvx",
      "args": ["solucortex-mcp"],
      "env": {
        "SOLUCORTEX_API_KEY": "scx_xxx",
        "SOLUCORTEX_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

ローカルクローンから

git clone https://github.com/soluai-spa/solucortex-mcp
cd solucortex-mcp
cp .env.example .env   # fill in your key
./run.sh               # loads .env, then runs via uv
# or, with SOLUCORTEX_* already exported: uv run solucortex-mcp

Docker

GHCR のビルド済みイメージ：

docker run --rm -i \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  ghcr.io/soluai-spa/solucortex-mcp:latest

または、自分でビルドします。

docker build -t solucortex-mcp .
docker run --rm -i \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  solucortex-mcp

サーバーは stdio 経由で MCP を使用するため、クライアントはサブプロセスとして起動します（-i は stdin を開いたままにします）。

エージェント向けの指示（AGENTS.md）

接続したら、エージェントに方法論も伝えましょう。templates/AGENTS.md をリポジトリのルートにコピーしてください（AGENTS.md または CLAUDE.md として機能します）。MCP ハンドシェイクにはすでにこれらの指示が含まれています。このファイルを使うと、コードとともに指示をバージョン管理し、独自の規約を追加できるほか、必要に応じてコメントアウトされている Claude Code フックの設定例を有効にして、確実に呼び出せるようにできます。

開発

uv sync
uv run solucortex-mcp            # run (stdio)
MCP_TRANSPORT=http uv run solucortex-mcp   # run (HTTP on :8080)
uv run pytest                    # test suite
npx @modelcontextprotocol/inspector uv run solucortex-mcp   # interactive test

注意事項

• メモリの type の語彙：標準セットは architecture, decision, risk, convention, bug_history, tech_debt, sensitive_module, learning, external_integration です。一部のバックエンドでは、旧セット（technical_decision, historical_bug, current_state, task_closure）も受け付けます。サーバーは type をそのまま渡し、HTTP 422 を返すため、もう一方のセットで再試行できます。
• メモリに実際のシークレットを保存しないでください。代わりに、場所、種類、重大度、実施した対応を記録してください。

ライセンス

MIT — LICENSE を参照してください。