codens-mcp 0.8.0

Unified MCP server for Codens family — Red (auto-fix), Blue (QA), Green (PRD), Auth, Purple (orchestration). All-in-one, no external purple-codens-mcp dependency.

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: [e-mail]
#   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:

Variable	Effect
CODENS_MCP_CREDENTIALS_FILE	Full path to the credentials JSON file
CODENS_MCP_CREDENTIALS_DIR	Directory holding credentials.json

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)

Tool	Description
purple_login	Log in via browser OAuth, device code, or email+password
purple_whoami	Show current authenticated user and organization

Project Setup (Purple)

Tool	Description
purple_analyze_repo	Scan local repo and return structured analysis
purple_list_projects	List all projects in the organization
purple_init_project	Full project setup: create → link repo → import instructions

Repository (Purple)

Tool	Description
purple_add_repository	Link a GitHub repository to a project
purple_list_repositories	List repositories linked to a project

Instruction Files (Purple)

Tool	Description
purple_import_instructions	Import CLAUDE.md + .claude/rules/ from GitHub
purple_list_instructions	List instruction files for a project
purple_sync_instructions	Diff local vs remote, update changed files

Workflow & Runs (Purple)

Tool	Description
purple_create_workflow	Create a new workflow
purple_get_run_status	Get current status of a workflow run
purple_list_runs	List workflow runs (filter by project/status)
purple_cancel_run	Cancel a running workflow
purple_inject_message	Inject a message into a heartbeat run
purple_subscribe_run_events	Stream SSE events for a workflow run

Log Retrieval (Purple)

Tool	Args	Description
purple_get_run_logs	api_url, organization_id, run_id	Get VPS job logs for a workflow run — returns jobs[] each with a presigned log_url (valid 1 hour)
purple_get_task_log_url	api_url, organization_id, project_id, task_id	Get S3 presigned log URL for a task's latest Claude Code job (valid 1 hour)

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

Tool	Description
red_create_bug_report	Create a bug report (agent endpoint)
red_get_bug_report	Get a bug report by ID
red_analyze_bug_report	Trigger AI analysis for a bug report
red_submit_bug_fix_plan_to_purple	Submit a fix plan to Purple for execution

Blue Codens — QA Automation

Tool	Description
blue_list_e2e_tests	List E2E tests
blue_generate_e2e_test	Generate an E2E test from a natural-language requirement
blue_run_e2e_test	Trigger a run for an existing E2E test
blue_get_e2e_test_results	Get results for an E2E test (latest run)

Green Codens — PRD Management

Tool	Description
green_create_consultation_with_message	Start a consultation and send the first message
green_send_consultation_message	Send a message in an existing consultation
green_convert_consultation_to_prd	Convert a consultation into a PRD
green_create_kickoff	Create a Kickoff in Green Codens

Auth Codens

Tool	Description
auth_agent_signup	Issue capability_token via existing user's API key
auth_get_pricing	Public pricing.json (no auth required)

Cross-product

Tool	Description
codens_register_project_unified	Register the same GitHub repo as a project across Purple/Red/Blue/Green in one call (best-effort, returns per-product IDs and any errors)

Changelog

See CHANGELOG.md.

License

MIT — Copyright 2026 Corevice Inc.