codens-mcp

Unified MCP server for the Codens family — lets Claude Code and other AI agents operate all Codens services through a single package.

Includes all 16 Purple tools (re-exported from purple-codens-mcp) plus new tools for Red (auto-fix), Blue (QA), Green (PRD), and Auth Codens.

📖 Full agent reference: help.codens.ai (JA) / help.codens.ai/en (EN). The help page is the canonical, machine-readable reference for using Codens from any AI agent — covers Quick Start, Device Code Flow login, four practical use cases, all 30 tools, the error envelope, pricing, and troubleshooting. AI crawlers can ingest llms.txt or the full plain-text dump at llms-full.txt.

Installation

pip install codens-mcp

Quick Start (Claude Code)

1. Install

pip install codens-mcp

2. Register the MCP server

Add to your .claude/settings.json:

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

Running codens-mcp with no arguments starts the MCP server (default serve subcommand) — same behavior as before.

3. Log in (once, via Device Code Flow)

codens-mcp login

The CLI prints a verification URL and a short user code:

============================================================
  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)...
============================================================

Open the URL on any browser, paste the code, and approve. The CLI detects the approval, fetches your JWT, and stores it at ~/.purple-codens/credentials.json (mode 0600). The token is accepted by all Codens family backends (Red / Blue / Green / Purple / Auth), so subsequent tool calls require no further login.

# Verify
codens-mcp whoami
# → Email: you@example.com
#   User ID: ...
#   Organization: ...

Use --auth-url / --api-url to point the login at non-default environments (e.g. --auth-url https://api.dev.auth.codens.ai).

Inside Claude Code you can also call the MCP purple_login tool instead — both flows produce the same credential file.

Credential storage location

By default credentials are stored at ~/.purple-codens/credentials.json (mode 0600). The access/refresh token pair is kept once in a shared block — all Codens backends accept the same SSO JWT — and the refresh token is long-lived (365 days, rotating), so the connection does not drop from ordinary disuse.

To run the MCP server for multiple users under a single OS account, point each user/session at its own credential file via environment variables:

CODENS_MCP_CREDENTIALS_FILE takes precedence. Example .mcp.json entry:

{
  "mcpServers": {
    "codens": {
      "command": "codens-mcp",
      "env": { "CODENS_MCP_CREDENTIALS_FILE": "/home/shared/.codens/alice.json" }
    }
  }
}

Available Tools (31 total)

Auth / Session (Purple)

Project Setup (Purple)

Repository (Purple)

Instruction Files (Purple)

Workflow & Runs (Purple)

Log Retrieval (Purple)

purple_get_run_logs — response shape

{
  "status": "success",
  "run_id": "<run_id>",
  "total": 2,
  "jobs": [
    {
      "job_id": "job_abc",
      "status": "completed",
      "log_url": "https://s3.amazonaws.com/...?X-Amz-Expires=3600&...",
      "started_at": "2026-05-14T10:00:00Z",
      "finished_at": "2026-05-14T10:05:00Z"
    }
  ]
}

purple_get_task_log_url — response shape

{
  "status": "success",
  "log_url": "https://s3.amazonaws.com/...?X-Amz-Expires=3600&...",
  "note": "Presigned URL is valid for 1 hour."
}

When no log exists yet, log_url is null (status remains "success").

Example: inspect a failed run

# 1. Check run status
status = purple_get_run_status(api_url=URL, organization_id=ORG, run_id=RUN)
# → {"status": "success", "run": {"status": "failed", ...}}

# 2. Fetch all job logs for that run
logs = purple_get_run_logs(api_url=URL, organization_id=ORG, run_id=RUN)
# → {"status": "success", "total": 1, "jobs": [{"log_url": "https://..."}]}

# 3. Download the log (URL valid for 1 hour)
import httpx
log_text = httpx.get(logs["jobs"][0]["log_url"]).text

Red Codens — Auto-Fix

Blue Codens — QA Automation

Green Codens — PRD Management

Auth Codens

Cross-product

Changelog

See CHANGELOG.md.

License

MIT — Copyright 2026 Corevice Inc.