Help / MCP setup

MCP setup

Make all 38 Codens tools callable from MCP-capable AI agents — Claude Code, Cursor, Cline, and others. About 5 minutes.

Step 1. Install

codens-mcp is published on PyPI as a Python package. Requires Python 3.13+.

pip install codens-mcp

# Check version
codens-mcp --version

Isolated installs via pipx install codens-mcp or uv tool install codens-mcp are also recommended. See PyPI: codens-mcp.

Step 2. Register the MCP server

The config file location differs by agent / IDE. Below are the most common clients.

Claude Code (official CLI)

Add this to ~/.claude/settings.json (or .claude/settings.local.json):

{
  "mcpServers": {
    "codens": {
      "command": "codens-mcp",
      "args": []
    }
  }
}

Cursor

Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "codens": {
      "command": "codens-mcp",
      "args": []
    }
  }
}

Cline / other MCP clients

Same idea — add a server entry with command: "codens-mcp". It uses stdio transport, so no special arguments are needed.

Run which codens-mcp first and pin the absolute path with "command": "/full/path/to/codens-mcp" in environments where PATH may not resolve (e.g. macOS launchd).

Step 3. Log in with Device Code Flow

Authentication uses Device Code Flow (RFC 8628). Because MCP runs over stdio, there is no browser redirect — Device Code Flow works the same on local, remote, SSH, or headless machines. The most reliable approach is running codens-mcp login from a terminal.

$ 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)

Procedure (must complete within 15 minutes)

Open https://auth.codens.ai/device in a browser.
Paste the displayed user_code (e.g. ABCD-1234) and click "Authorize".
Log in to Codens (if you weren't already) and approve access.
The CLI is polling — once you authorize, the token is saved to ~/.purple-codens/credentials.json (mode 0600).
Verify with codens-mcp whoami; it should print your email, user_id, and organization.

To target a non-default environment (e.g. dev): codens-mcp login --auth-url https://api.dev.auth.codens.ai --api-url https://api.dev.purple.codens.ai.

If you see expired_token

user_code lifetime is 15 minutes. If you wait too long, the CLI fails with expired_token. Just run codens-mcp login again to get a fresh code. If it keeps expiring, open https://auth.codens.ai/device in advance, then run the CLI and paste the new code immediately.

Logging in from inside the agent

If you can't run a CLI, call the purple_auth tool from the agent instead. Note: stdio buffering on the MCP server side can occasionally stall polling. Prefer the CLI when available.

// Example agent call
await tools.purple_auth({
  action: "login",
  use_device_code: true,
  auth_service_url: "https://api.auth.codens.ai"
});

// Response
{
  "status": "success",
  "message": "Logged in as you@example.com",
  "user_id": "...",
  "org_id": "...",
  "org_name": "..."
}

Either way, the token is saved to ~/.purple-codens/credentials.json and shared across Red / Blue / Green / Purple / Auth.

Verify the connection

Restart your agent and make sure the Codens tools appear.

# Terminal
codens-mcp whoami
# → prints email / user_id / organizations

# Agent (Claude Code etc.)
> /mcp
# → "codens" server appears
# → list tools shows purple_*, red_*, blue_*, green_*, auth_*, codens_register_project_unified

If tools are missing, see Troubleshooting.

Calling the REST API directly

For custom agents, CI jobs, or backend integrations, you can hit the REST API directly without MCP. Get a Bearer token via Device Code Flow (or Authorization Code + PKCE) from Auth Codens.

# 1. Start device authorization
curl -X POST https://api.auth.codens.ai/oauth/device/authorize \
  -d "client_id=codens-mcp&scope=openid email profile"

# → returns device_code / user_code / verification_uri

# 2. User opens verification_uri in a browser and enters user_code

# 3. Poll for the access token
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. Call any service
curl https://api.purple.codens.ai/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGc..."

OpenAPI is available at each service's /docs: Purple / Red / Blue / Green.

Next steps

Purple setup

Register your first project

Use cases

Four canonical scenarios

All 38 tools

Action-dispatch reference