ossian-mcp

ossian-mcp

Ossian 用の MCP サーバーです。組織独自のドキュメントに質問すると、回答の根拠となった箇所を取得できます。また、会話が終わった後も保持されるエージェント用のメモリも利用できます。

Ossian がサーバーで、これはエージェントの前段に配置するアダプターです。接続先となる稼働中の Ossian が必要です。docker compose up についてはこちらの READMEをご覧ください。

エージェントに提供する機能

ツールはアクセスモードによって制限されます（デフォルトで安全を参照）。サーバーは読み取り専用で起動し、モードを引き上げるまでは読み取り用の 4 つのツールのみを公開します。

ツール	用途	必要なモード
ask_documents	引用付きでコーパスから回答します。回答できない場合はその旨を伝えます	read-only
list_namespaces	存在する各スライスと、それぞれに含まれるデータ量を確認します	read-only
list_documents	回答に利用できるものと、まだ取り込み中のものを確認します	read-only
recall	現在関連する情報を、関連性、重要度、新しさの順にランク付けして取得します	read-only
add_document_from_url	公開ページをコーパスに取り込みます	read-write
remember	保存する価値のある設定、事実、決定を記録します	read-write
forget_session	1 つの会話のメモリを消去します（元に戻せません）	admin + OSSIAN_ALLOW_FORGET

インストール

npm install -g ossian-mcp

稼働中の Ossian と API キーが必要です。コンソール（Console → API keys）から発行するか、次のコマンドを実行してください。

curl -X POST "$OSSIAN_URL/api/admin/api-keys" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"mcp","roles":["ossian-user"],"namespace":"handbooks"}'

機能する範囲で最も制限の厳しいスコープをキーに付与してください。namespace を指定すると 1 つのスライスに制限されるため、キーが漏えいしても、そのエージェント向けのデータしか読み取れません。

設定

{
  "mcpServers": {
    "ossian": {
      "command": "ossian-mcp",
      "env": {
        "OSSIAN_URL": "http://localhost:8081",
        "OSSIAN_API_KEY": "osk_...",
        "OSSIAN_AGENT_ID": "support-bot",
        "OSSIAN_MODE": "read-only"
      }
    }
  }
}

OSSIAN_AGENT_ID を指定すると、エージェントごとにメモリを分離できます。同じ ID を共有する 2 つのエージェントは記憶を共有します。そうしたい場合もありますが、通常は共有しません。

Claude Code / Cursor / Codex / VS Code / Windsurf の設定例についてはdocs/CLIENTS.mdを、サポートされているすべての変数については.env.exampleをご覧ください。

デフォルトで安全

このサーバーは、Ossian API キーに加えてアクセスモデルを適用します。キー自体のロールや名前空間による制限に対する、多層防御です。ポリシーは環境変数（.env.example）から読み込み、src/security.tsで適用します。

• OSSIAN_MODE — read-only（デフォルト）→ read-write → admin。モードで機能が許可されている場合にのみツールが登録されます。読み取り専用モードでは 4 つのツールが公開されます。取り込みと記憶には read-write、忘却には admin が必要です。
• OSSIAN_ALLOW_FORGET — forget_session はメモリを元に戻せない形で消去するため、admin モードに加えてこのフラグも必要です。
• OSSIAN_NAMESPACE_ALLOWLIST / OSSIAN_PROTECTED_NAMESPACES — 操作可能なスライスを制限し、読み取りは許可しても取り込みは禁止するスライスを指定します。
• OSSIAN_DRY_RUN — 書き込み（取り込み / 記憶 / 忘却）を実行せず、検証してログに記録します。
• OSSIAN_AUDIT_LOG — 保護対象の操作ごとに、stderr に JSON 形式の監査ログを出力します（デフォルトで有効）。
• 対話型の確認 — クライアントが MCP のエリシテーションに対応している場合、forget_session はセッションのメモリを消去する前に、人間に承認を求めます。エリシテーションに対応していないクライアントでは、OSSIAN_ALLOW_FORGET による制限が適用されます。

最も重要な制御は引き続き API キーです。機能する範囲で最も制限の厳しいキーを発行してください。詳しくはSECURITY.mdをご覧ください。

知っておくべきことが2つあります

「見つからない」も回答です。 ask_documents は、コーパス内に回答を裏付ける情報がない場合、回答を拒否します。また、ツールの説明では、一般知識で補うのではなく、その旨を報告するようモデルに指示しています。会社の方針として提示される作り話を防ぐことが、このシステムの目的です。ご自身のプロンプトで、この点を覆い隠さないでください。

メモリはコーパスではありません。 recall はエージェントに伝えられた内容を検索し、ask_documents は組織が文書化した内容を検索します。これらは意図的に別々のストアになっています。方針に関する回答でメモリが引用として表示されると、方針そのものとの区別がつかなくなるためです。

開発

npm install
npm run build
OSSIAN_URL=http://localhost:8081 OSSIAN_API_KEY=osk_… node dist/index.js

標準入出力を介して JSON-RPC で通信するため、フレームが届くまで待機します。手動で動作させるには、次のようにします。

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

診断情報は意図的に標準エラー出力へ送られます。プロトコルフレーム以外の内容が標準出力に書き込まれると、ストリームが破損します。この場合、ログ行を出力したサーバーではなく、解析できないクライアントとしてエラーが現れます。

ライセンス

Apache-2.0