atlas-mcp

atlas-mcp

AI エージェント向けの事前アクション認可を、MCP サーバーとして提供します。

エージェントがデータを削除したり、デプロイしたり、支出したりする前に、Atlas に問い合わせます。Atlas はリクエストを署名済みの委任チェーンと照合し、証跡とともに permit、deny、または escalate を返します。アクションの後、エージェントは atlas_commit_effect を使って実際に何が起きたかを報告します。すべてのステップは、ハッシュチェーンで連結され、ML-DSA-65 で署名された監査ログに記録されます。

$ npx -y @corpussanctum/atlas-mcp demo

  You (alice) delegate to claude: database work in STAGING only.

  Claude: delete rows in staging
    -> PERMIT    rcpt_ec14…  authorized by 1-link delegation chain from user:alice

  Claude: delete rows in PRODUCTION
    -> DENY      rcpt_876f…  effect targets environment 'production';
                             delegated authority (grant grt_c9c8…) only permits staging

  Claude: write to staging (grant says writes need a human)
    -> ESCALATE  rcpt_a8d7…  action 'db.write' requires human approval

クイックスタート（5 分）

1. サーバーを登録します。

Claude Code：

claude mcp add atlas -- npx -y @corpussanctum/atlas-mcp

Claude Desktop（claude_desktop_config.json）、または任意の MCP クライアント：

{ "mcpServers": { "atlas": { "command": "npx", "args": ["-y", "@corpussanctum/atlas-mcp"] } } }

Codex（~/.codex/config.toml）：

[mcp_servers.atlas]
command = "npx"
args = ["-y", "@corpussanctum/atlas-mcp"]

2. 権限を委任します。 プリンシパルであるあなたが、エージェントに許可を付与します：

npx -y @corpussanctum/atlas-mcp grant --principal user:alice --subject agent:claude \
  --allow 'db.*' --env staging --escalate db.write --ttl-hours 8
# prints the grant JSON; note its "id" (grt_…)

3. エージェントにルールを伝えます。 CLAUDE.md / AGENTS.md に追記します（examples/CLAUDE.md.snippet を参照）：

破壊的な操作、本番環境での操作、デプロイ、または支出を伴う操作の前に、エージェントを agent:claude、プリンシパルを user:alice、delegation_chain を ["grt_…"] として、アクションとすべての効果を指定し、atlas_authorize を呼び出してください。permit の場合にのみ実行してください。その後、atlas_commit_effect を呼び出してください。

4. 人間としてエスカレーションを承認します。 エージェントが自分自身を承認できないよう、承認は意図的に MCP ツールではありません：

npx -y @corpussanctum/atlas-mcp resolve rcpt_a8d7… approve
npx -y @corpussanctum/atlas-mcp verify            # check the audit chain and signatures

ツール

ツール	用途
atlas_authorize	{agent, principal, requested_action, effects[], delegation_chain[]} → {decision, reason, scope, receipt_id}
atlas_commit_effect	証跡に基づいて実際に起きたことを報告します。証跡ごとにコミットは 1 回です。証跡の対象外の効果は violation としてフラグが付けられます。
atlas_receipt_status	ready、pending_approval、rejected、denied、committed、expired
atlas_verify_audit	SHA3-256 チェーンとすべての ML-DSA-65 署名を検証します

判定の仕組み

• 許可は、付与者から対象者への許可を定めます。対象者は allow アクションを実行できますが、deny アクションは除きます。また、environments に指定された環境でのみ、resources に指定されたリソースのみを対象とし、escalate アクションには人間の承認が必要です。許可はローカル発行者キーで署名され、監査ログに記録されます。
• チェーンは、プリンシパル → エージェント → サブエージェントとつながります。途切れておらず、有効期限切れでも失効済みでもない必要があり、各リンクに進むにつれて権限の範囲が狭まる必要があります。親の許可より範囲を広げる子の許可は拒否されます。
• 積集合のセマンティクス： すべてのリンクが、それぞれ独立してアクションと各効果を許可する必要があります。どれかのリンクを失効させると、その下位のすべての権限が無効になります。
• フェイルクローズ： 不明な許可、不正な署名、環境が制限された許可での環境の指定漏れ、不正な形式のリクエストは、すべて拒否されます。サーバーが信頼するのは、許可について自ら記録した内容であり、呼び出し元の申告ではありません。
• 証跡は 15 分後に期限切れになります。許可／承認の対象となるのは、明示された効果のみです。

適用する：Claude Code フック

MCP ツールは、エージェントが自ら選んで呼び出すゲートです。フックを使うと、Claude Code ではチェックをスキップできなくなります。モデルの外側で、ゲート対象のツール呼び出しごとに実行されるため、エージェントがチェックを忘れたり、deny を覆そうとしたりすることはできません。

npm i -g @corpussanctum/atlas-mcp       # a global install avoids npx startup cost on every tool call
atlas-mcp hook init --principal user:alice

hook init は ~/.atlas-mcp/hook.json を書き込み、スターター許可（30 日間有効、環境は dev と staging、shell.deploy と shell.delete は事前確認）を発行し、~/.claude/settings.json に貼り付ける settings.json ブロックを表示します。

各ツール呼び出しで行われること

Claude Code のツール呼び出し	Atlas のアクション	結果
dev での npm test	shell.exec	判定なし：Claude Code の通常の権限が適用されます
psql … production	production での shell.exec	拒否：委任された権限で許可されているのは dev と staging のみです
rm -rf dist、git push --force、drop table	shell.delete	確認：Claude Code が確認を求めます。承認すると、その内容が承認として記録されます
kubectl apply、terraform apply、npm publish	shell.deploy	確認
Write / Edit / MultiEdit	file.write	許可に従います
mcp__server__tool	mcp.server.tool	許可に従います
Read、Grep、Glob、Atlas 自身のツール	ゲート対象外

その後、PostToolUse フックが成功・失敗にかかわらず証跡を署名済み監査ログにコミットします。atlas-mcp verify でいつでも確認できます。

調整

~/.atlas-mcp/hook.json を編集します。

{
  "agent": "agent:claude-code",
  "principal": "user:alice",
  "delegation_chain": ["grt_…"],
  "default_environment": "dev",
  "environments": [{ "match": "\\b(prod|production|live)\\b", "environment": "production" }],
  "rules": [{ "tool": "^Bash$", "match": "^make release", "action": "shell.deploy", "effect_type": "deploy" }],
  "on_permit": "defer"
}

on_permit: "allow" を指定すると、Atlas の許可により Claude Code 独自のプロンプトを省略できます。デフォルトの defer では、Claude Code のプロンプトを第2の層として維持します。

このツールが行わないこと（お読みください）

• 分類はパターンマッチングです。 Atlas が認識しないコマンドは通常の shell.exec として扱われ、環境はコマンド内の単語（prod、production、staging）から推測されます。./deploy.sh や、環境を示す単語が含まれない接続文字列は、dev として通過します。独自のツールには rules と environments を追加してください。これはミスを防ぐための注意喚起であり、監査記録です。意図を積極的に隠すエージェントへの防御ではありません。
• 記録されるのは分類された影響であり、実際に確認された影響ではありません。 監査ログには、プロセスが実際に行ったことではなく、Atlas が呼び出しによって起こると判断した内容が記録されます。
• フックの失敗。 フックは、自身のエラー（設定ファイルの欠落、不正な許可）を検出できる場合は deny を返します。ハードクラッシュやタイムアウトは、お使いのビルドがフックハンドラーで "onFailure": "block" をサポートしていない限り、Claude Code によってブロックされません（最近のバージョンでドキュメントに記載されています）。サポートされている場合は、両方のフックエントリーに追加してください。
• 権限モード。 Claude Code のドキュメントには、フックの deny が --permission-mode bypassPermissions でも有効かどうか記載されていません。Claude Code 2.1.296（Claude Code）でテストしたところ、bypassPermissions の実行時に拒否されたコマンドは実行されませんでした（制御コマンドは実行され、コミットされました）。Claude Code をアップグレードした後は、再テストしてください。
• 自己保護は部分的です。 ~/.atlas-mcp の編集や、その名前を指定するコマンドは拒否されますが、シェルからファイルにアクセスする方法は多数あります。それが重要な場合は、データディレクトリの所有者とは異なる OS ユーザーとしてエージェントを実行してください。
• Claude Code 専用です。他のクライアントでは、独自の強制ポイントが必要です。

利用する前にお読みください

• これはエージェントが参照するゲートであり、サンドボックスではありません。 MCP ツール単独では、ツールを呼び出さないと決めたエージェントや、影響について虚偽を述べるエージェントを阻止できません。v0.1 が提供するのは、署名済みで検証可能な記録と、それを使って強制するための判断です。Claude Code では、上記のフックを使って拘束力を持たせてください。それ以外では、ツールプロキシやネットワーク／認証情報の分離と組み合わせてください。atlas_commit_effect は、報告された不一致を検出して記録します。
• 発行者キーは ~/.atlas-mcp/issuer.json に暗号化されずに保存されます（モード 0600）。SSH キーと同様にディレクトリを保護してください。キーを読み取れる人は、許可を偽造できます。
• ローカルオペレーターの承認には、ローカルのシェルアクセスが必要です。v0.1 にはリモート承認チャネルがありません。
• コンプライアンス認証ではありません。暗号技術の選択は親プロジェクトの前提に従っており、外部監査は実施されていません。

データと設定

ATLAS_MCP_DATA_DIR（デフォルトは ~/.atlas-mcp）に issuer.json と audit.jsonl が保存されます。データがマシンの外部に送信されることはありません。

Docker

docker build -t atlas-mcp .
docker run -i --rm -v atlas-data:/data atlas-mcp

Atlas Protocol との関係

atlas-protocol は、完全なガバナンスゲートキーパーです（Telegram オペレーターリレー、96 ルールのポリシーエンジン、エージェント ID レジストリ、行動ベースライン、近接性）。atlas-mcp は、その中から抽出された最小限の実用的な部分で、1行のコマンドでインストールできます。

開発

npm install && npm test

Apache-2.0。