Cortex MCP — Multi-Level Reasoning Server

Cortex MCP

深さレベルを設定でき、セッションベースの状態管理、構造化された思考入力、リアルタイムのトレースリソースを備えた、多段階推論 MCP サーバーです。

概要

Cortex MCP は、状態を保持し、深さを制御できる推論用の stdio 専用 MCP サーバーです。src/index.ts のランタイムエントリーポイントは createServer() を StdioServerTransport に接続し、src/server.ts のサーバー機能では、単一のセッションベース推論エンジンを中心に、ツール、プロンプト、補完、ログ、購読可能なリソースを有効にします。

Inspector で確認された実際の MCP 機能は、1 個のツール、6 個の具体的なリソース、4 個のリソーステンプレート、7 個のプロンプトです。セッションはメモリ内に保存され、MCP リソースとして公開され、プロセスの再起動時に消去されます。

主な機能

• reasoning_think は、段階的なセッション、run_to_completion による一括実行、ロールバック、早期結論、構造化された observation／hypothesis／evaluation 入力に対応します。
• エンジンには、basic、normal、high、expert の 4 段階の深さが組み込まれており、それぞれに上限付きの思考範囲とトークン予算が設定されています。
• プロンプトヘルパーは、reasoning.basic、reasoning.normal、reasoning.high、reasoning.expert、reasoning.continue、reasoning.retry、get-help を提供します。
• リソースエンドポイントは、内部ドキュメントに加え、実行中のセッション一覧、セッションごとの JSON 表示、完全な Markdown トレース、個々の思考ドキュメントを公開します。
• completable() とリソーステンプレートの補完フックを通じて、深さレベル、セッション ID、思考名の補完を利用できます。

要件

• ローカルで npx または npm を使用する場合は、Node.js >=24 が必要です。
• stdio トランスポートに対応した MCP クライアントが必要です。
• 任意：Dockerfile で定義されたコンテナイメージをビルドまたは実行する場合は、Docker が必要です。

クイックスタート

次の標準的な MCP クライアント設定を使用します。

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

クライアント設定

{
  "servers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

code --add-mcp '{"name":"cortex-mcp","command":"npx","args":["-y","@j0hanz/cortex-mcp@latest"]}'

{
  "servers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

code-insiders --add-mcp '{"name":"cortex-mcp","command":"npx","args":["-y","@j0hanz/cortex-mcp@latest"]}'

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

claude mcp add cortex-mcp -- npx -y @j0hanz/cortex-mcp@latest

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

amp mcp add cortex-mcp -- npx -y @j0hanz/cortex-mcp@latest

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "servers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "context_servers": {
    "cortex-mcp": {
      "settings": {
        "command": "npx",
        "args": ["-y", "@j0hanz/cortex-mcp@latest"]
      }
    }
  }
}

{
  "augment.advanced": {
    "mcpServers": [
      {
        "id": "cortex-mcp",
        "command": "npx",
        "args": ["-y", "@j0hanz/cortex-mcp@latest"]
      }
    ]
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "cortex-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/cortex-mcp@latest"]
    }
  }
}

ユースケース

適切な深さで範囲を限定した推論を開始する

クライアントがプロンプトを起点とするエントリーポイントを求めている場合は、reasoning.basic、reasoning.normal、reasoning.high、reasoning.expert を使用するか、query、level、最初の thought を指定して reasoning_think を直接呼び出します。各応答は、現在のセッション状態と、クライアントが続行する方法を示す summary 文字列を返します。

関連ツール：reasoning_think
関連プロンプト：reasoning.basic、reasoning.normal、reasoning.high、reasoning.expert

アクティブなセッションを続行、再試行、またはバッチ処理する

sessionId を再利用して以前のトレースを続行します。残りの思考入力がすでにある場合は、runMode="run_to_completion" に切り替えるか、続行プロンプトと再試行プロンプトを使用して次の呼び出しペイロードを生成します。ハンドラーは、トレースを修正したり早期に終了したりするための rollbackToStep と isConclusion もサポートしています。

関連ツール：reasoning_think
関連プロンプト：reasoning.continue、reasoning.retry

ツールを再実行せずにライブトレースを確認する

アクティブなセッション一覧は reasoning://sessions、JSON 詳細ビューは reasoning://sessions/{sessionId}、Markdown の書き起こしは reasoning://sessions/{sessionId}/trace、単一の思考は reasoning://sessions/{sessionId}/thoughts/{thoughtName} から読み取れます。これにより、クライアントは次のツール呼び出しとは独立して、進行状況を提示したりセッションを監査したりできます。

関連リソース：reasoning://sessions、reasoning://sessions/{sessionId}、reasoning://sessions/{sessionId}/trace、reasoning://sessions/{sessionId}/thoughts/{thoughtName}

アーキテクチャ

[MCP Client]
    |
    | stdio
    v
[src/index.ts]
    createServer()
    -> new StdioServerTransport()
    -> server.connect(transport)
    |
    v
[src/server.ts]
    McpServer("cortex-mcp")
    capabilities:
      - tools
      - prompts
      - completions
      - logging
      - resources { subscribe: true, listChanged: true }
    |
    +--> tools/call
    |     -> reasoning_think
    |     -> src/tools/reasoning-think.ts
    |     -> ReasoningThinkInputSchema / ReasoningThinkToolOutputSchema
    |     -> src/engine/reasoner.ts
    |     -> SessionStore
    |
    +--> prompts/get
    |     -> src/prompts/index.ts
    |
    +--> resources/read
    |     -> src/resources/index.ts
    |     -> internal://* and reasoning://sessions/*
    |
    +--> notifications
          -> logging messages
          -> resources/list_changed
          -> resources/updated
          -> notifications/progress

リクエストのライフサイクル

[Client] -- initialize --> [Server]
[Server] -- serverInfo + capabilities --> [Client]
[Client] -- notifications/initialized --> [Server]
[Client] -- tools/call {name: "reasoning_think", arguments} --> [Handler]
[Handler] -- validate args --> [Reasoner + SessionStore]
[Reasoner] -- progress/resource events --> [Server notifications]
[Handler] -- structuredContent + optional trace resource --> [Client]

MCP インターフェース

ツール

reasoning_think

複数ステップのセッションを作成・継続するための状態を保持する推論ツールです。1 ステップずつの対話的な呼び出し、run_to_completion によるバッチ処理、観察・仮説・評価の構造化された入力、ロールバック、早期終了に対応し、構造化されたセッション状態を返します。

1. [Client] -- tools/call {name: "reasoning_think", arguments} --> [Server]
   Transport: stdio
2. [Server] -- dispatch("reasoning_think") --> [Handler: src/tools/reasoning-think.ts]
3. [Handler] -- validate(ReasoningThinkInputSchema) --> [src/engine/reasoner.ts]
4. [Reasoner] -- create/update session --> [src/engine/session-store.ts]
5. [Handler] -- structuredContent + optional embedded trace resource --> [Client]

プロンプト

MCP の機能

ツールのアノテーション

構造化出力

• reasoning_think は outputSchema を宣言し、structuredContent を返します。トレースが十分に小さい場合は、埋め込みトレースリソースも含まれます。根拠：src/tools/reasoning-think.ts:498、src/lib/mcp.ts:97-114。

設定

メモ

ソースでは、HTTP のホスト／ポート設定は定義されていません。環境関連で確認できるその他の情報は、Docker イメージ内の NODE_ENV=production と、ローカルの dev:run スクリプト内の --env-file=.env のみです。

セキュリティ

メモ

サーバーは stdio トランスポートのみを公開するため、現在のソースには認証、OAuth、HTTP オリジンチェック、レート制限の制御は実装されていません。

開発

診断、カバレッジ、アセットのコピー、knip 用の追加ヘルパースクリプトは package.json で定義されています。

ビルドとリリース

• .github/workflows/release.yml は package.json と server.json のバージョンを更新し、タグ付けと GitHub リリースの作成前に npm run lint、npm run type-check、npm run test、npm run build を実行します。
• 同じワークフローで Trusted Publishing を使ってパッケージを npm に公開し、mcp-publisher で MCP Registry に公開し、マルチアーキテクチャの Docker イメージを ghcr.io にプッシュします。
• Dockerfile はマルチステージの Node 24 Alpine ビルドを使用し、開発用依存関係を削除してから、リリース済みコンテナを mcp ユーザーとして実行します。

トラブルシューティング

• セッションはメモリ上に保持され、デフォルトでは 30 分後に期限切れになります。E_SESSION_NOT_FOUND を受け取った場合は、新しいセッションを開始するか、CORTEX_SESSION_TTL_MS を大きくしてください。
• runMode="run_to_completion" では、残りのステップをカバーするのに十分な数の thought エントリーが必要です。各ステップの後にサーバーから応答を返す場合は、デフォルトの step モードを使用してください。
• stdio トランスポートでは、サーバープロセスの周囲に独自の stdout ロギングを追加しないでください。このサーバーは MCP ロギング経由でログを出力し、失敗時には stderr にフォールバックします。

クレジット

コントリビューションとライセンス

• ライセンス：MIT
• プルリクエストによるコントリビューションを歓迎します。