Help / MCP セットアップ
Claude Code / Cursor / Cline などの MCP 対応 AI agent から、Codens family の全 38 tools を呼び出せるようにします。所要時間は約 5 分です。
codens-mcp は Python パッケージとして PyPI で配布しています。Python 3.13 以上が必要です。
pip install codens-mcp
# バージョン確認
codens-mcp --versionpipx install codens-mcp もしくは uv tool install codens-mcp のような isolated install も推奨です。詳しくは PyPI: codens-mcp を参照。
利用する AI agent / IDE ごとに設定ファイルが異なります。代表的なクライアントの設定例を示します。
~/.claude/settings.json （または .claude/settings.local.json）に以下を追加：
{
"mcpServers": {
"codens": {
"command": "codens-mcp",
"args": []
}
}
}Settings → MCP → Add new MCP server で以下を入力するか、~/.cursor/mcp.json を直接編集：
{
"mcpServers": {
"codens": {
"command": "codens-mcp",
"args": []
}
}
}同じく command: "codens-mcp" を MCP サーバ設定に追加。stdio transport で動作するため、特殊な引数は不要です。
which codens-mcp でフルパスを確認しておくと、PATH が解決できない環境（macOS の launchd 配下など）でも確実です。その場合は "command": "/full/path/to/codens-mcp" と書きます。
認証は Device Code Flow（RFC 8628）で行います。MCP は stdio transport で動くためブラウザリダイレクトが使えず、リモート / SSH / headless 環境でも同じ手順で認証できる方式です。ターミナルから codens-mcp login を直接実行するのが最も確実です。
$ codens-mcp login
============================================================
Device Authorization Required
============================================================
1. Open this URL on any device:
https://auth.codens.ai/device
2. Enter this code when prompted:
ABCD-1234
Waiting for authorization (expires in 15 minutes)...
============================================================
✓ Authorized as you@example.com
Token saved to ~/.purple-codens/credentials.json (mode 0600)手順（15 分以内に完了してください）
user_code（例: ABCD-1234）を入力欄に貼り付けて「Authorize」~/.purple-codens/credentials.json（mode 0600）に保存codens-mcp whoami で email / user_id / organization が表示されれば成功非デフォルト環境（dev など）に向ける場合は codens-mcp login --auth-url https://api.dev.auth.codens.ai --api-url https://api.dev.purple.codens.ai のように指定。
expired_token が出たら
user_code の有効期限は 15 分です。表示後に認可しないと expired_token エラーで失敗します。その場合は codens-mcp login を再度実行すると新しい code が発行されます。連続で expired する場合は、ブラウザを先に https://auth.codens.ai/device で開いておき、CLI 実行直後に code を貼り付けるのが確実です。
agent 内からログインする場合
CLI が使えない場合は agent から purple_auth tool を呼ぶこともできます。ただし MCP server の polling と stdio 出力のバッファリングが噛み合わず応答が返らないケースが報告されているため、CLI が使える環境では CLI を推奨します。
// agent からの呼び出し例
await tools.purple_auth({
action: "login",
use_device_code: true,
auth_service_url: "https://api.auth.codens.ai"
});
// 戻り値
{
"status": "success",
"message": "Logged in as you@example.com",
"user_id": "...",
"org_id": "...",
"org_name": "..."
}CLI / agent どちらの方式でも token は ~/.purple-codens/credentials.json に保存され、Red / Blue / Green / Purple / Auth 全サービスで共通に利用できます。
agent を再起動して、Codens 系の tool が見える状態になったか確認します。
# ターミナル側
codens-mcp whoami
# → email / user_id / organizations が表示される
# agent 側（Claude Code 等）
> /mcp
# → "codens" サーバが表示される
# → list tools で purple_*, red_*, blue_*, green_*, auth_*, codens_register_project_unified が見えるtool が見えない場合は トラブルシューティング を参照してください。
独自 agent / CI ジョブ / バックエンド統合のために、MCP を介さず REST API を直接呼ぶことも可能です。Bearer token は Auth Codens の Device Code Flow（または Authorization Code + PKCE）で取得します。
# 1. Device authorization を開始
curl -X POST https://api.auth.codens.ai/oauth/device/authorize \
-d "client_id=codens-mcp&scope=openid email profile"
# → device_code / user_code / verification_uri が返る
# 2. ユーザーがブラウザで verification_uri を開き、user_code を入力
# 3. アクセストークン取得 (poll)
curl -X POST https://api.auth.codens.ai/oauth/token \
-d "grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=...&client_id=codens-mcp"
# 4. 任意のサービスを呼ぶ
curl https://api.purple.codens.ai/api/v1/auth/me \
-H "Authorization: Bearer eyJhbGc..."OpenAPI 仕様は各サービスの /docs でも参照できます: Purple / Red / Blue / Green。