expired_token blocks login

The Device Code Flow user_code is valid for about 5 minutes. Open https://auth.codens.ai/device immediately after the tool prints the code. If you keep failing, open the URL before calling codens_login and paste the code as soon as it appears. A fresh code is issued every time you call the tool.

codens_login appears to hang from inside the agent

Run purple-codens-mcp login from a terminal directly. Once finished, the token is in your OS secure store. Restart the agent and every Codens tool authenticates automatically without further prompts.

The agent doesn't see the MCP tools

Check that ~/.claude/settings.json mcpServers.codens.command is the absolute path to your installed codens-mcp. Run which codens-mcp and use that path.

UNAUTHORIZED errors are returned repeatedly

The token has likely expired. Run codens_login again, or include auth_token_refresh in the agent's automatic flow.

The workflow stays pending and doesn't start

The VPS pool may be at capacity. Check purple_workflow_status.queue_position. If it stays unmoved for 15+ minutes, contact support with the trace_id.

What are the three ways to access Codens?

(1) MCP — pip install codens-mcp and every tool becomes callable from Claude Code, Cursor, Cline, etc. (recommended). (2) REST API at api.{red,blue,green,purple,auth}.codens.ai. (3) Stripe Projects auto-signup (planned).

How is pricing structured?

Usage-based JPY (1 credit = JPY 0.01). New organizations receive a 1,000 JPY credit on first signup. The machine-readable spec is at https://api.auth.codens.ai/.well-known/pricing.json.

Codens Help — Use the Codens family from any AI agent

1. Access paths — three options

Codens can be reached through three paths. Using MCP is the simplest: any MCP-compatible client (Claude Code, Cursor, Cline, etc.) gains access to all tools automatically.

Path	Audience	Characteristics	Recommendation
Via MCP	Claude Code, Cursor, Cline, and other MCP-capable agents	Install `codens-mcp` and register it in `~/.claude/settings.json`; all 30 tools become available. Authentication uses an OAuth flow, and credit and billing are linked automatically.	Recommended
REST API direct	Custom agents, CI jobs, and backend integrations	Call `https://api.purple.codens.ai` and the corresponding service endpoints directly using their OpenAPI specs. Bearer tokens are issued by Auth Codens. The `Idempotency-Key` header is supported.	—
Stripe Projects auto-signup	Future: agents and individual users without an existing contract	Onboard through the Stripe Customer Portal with usage-based pricing. The first credit grant is applied automatically, allowing immediate use of Codens. (Planned.)	Coming soon

2. Quick Start (via MCP)

Three steps put every Codens tool within reach of your agent.

Step 1. Install

pip install codens-mcp

Step 2. Register in `~/.claude/settings.json`

{
  "mcpServers": {
    "codens": {
      "command": "codens-mcp",
      "args": ["serve"],
      "env": {
        "CODENS_AUTH_URL": "https://auth.codens.ai"
      }
    }
  }
}

The same MCP server configuration is supported in Cursor and Cline. Adapt the JSON to each client's settings file format.

Step 3. First-time authentication

Authentication uses the Device Code Flow (RFC 8628). Because MCP runs over stdio transport, browser redirects aren't available — Device Code Flow lets remote, SSH, and headless environments authenticate with the same procedure. When you call codens_login from your agent, a user_code and authorization URL are displayed.

// Example agent invocation
await tools.codens_login({});

// Response (shown in your agent's output)
{
  "verification_uri": "https://auth.codens.ai/device",
  "verification_uri_complete": "https://auth.codens.ai/device?user_code=WDJB-MJHT",
  "user_code": "WDJB-MJHT",
  "expires_in": 300,
  "interval": 5
}

Steps (complete within 5 minutes)

Open https://auth.codens.ai/device in your browser (or click the verification_uri_complete URL the agent prints).
Paste the user_code shown by the agent (e.g. WDJB-MJHT) into the input field and click "Authorize".
Sign in to Codens if prompted, then approve the access request.
The agent automatically polls until authorization is complete and stores the token in your operating system's secure store. Subsequent tool calls authenticate automatically.

If you see expired_token

The user_code is valid for about 5 minutes. If you don't authorize quickly enough, the flow fails with expired_token. To recover, call the same tool (codens_login) again — a fresh code is issued each time. If this keeps expiring, open https://auth.codens.ai/device in your browser before invoking the tool, then paste the new code as soon as it appears.

If the agent call hangs — log in via CLI instead

A few users have reported that codens_login invoked from inside the agent (Claude Code etc.) appears to hang indefinitely (the MCP server's polling and stdio buffering can interact badly). The reliable workaround is to run the CLI directly from a terminal:

$ purple-codens-mcp login

Visit this URL on any device to authorize:
  https://auth.codens.ai/device?user_code=WDJB-MJHT
Or enter this code at https://auth.codens.ai/device :
  WDJB-MJHT

Waiting for authorization... (expires in 300s)
✓ Authorized as you@example.com (org_01H...)
Token saved to ~/.config/codens/credentials.json

Once the CLI finishes, the token is in your secure store. Restart the agent and every Codens tool will authenticate automatically — no need to call codens_login from inside the agent.

Once authorized

From this point forward, every Purple, Red, Blue, Green, and Auth tool is callable from your agent. The next section, "Four use cases", shows concrete examples.

3. Four practical use cases

Four representative scenarios are shown below. Each is illustrated with a sample dialogue and the sequence of tools that the agent invokes.

A. Hand a development task to Codens for automatic implementation — Purple Codens

Pull an implementation task out of your local repository and let Claude Code, running on a Purple Codens VPS, complete the work and open a pull request. Multiple tasks can run in parallel.

User: "Add rate limiting to the login API in auth-codens and open a PR."

Agent: -> purple_workflow_create({
    repo: "Corevice/auth-codens",
    title: "Add rate limiting to login API",
    description: "Apply 10 req/min per IP using a Redis-backed limiter. Add tests.",
    base_branch: "develop"
  })
  -> Poll progress with purple_workflow_status({ workflow_id })
  -> Share the PR URL with the user once the workflow completes.

B. Bug report to automated fix PR — Red into Purple chain

Errors detected by Sentry or reported manually are analyzed by Red Codens, and Purple Codens then produces the fix PR. Red can issue a PR on its own, but chaining into Purple yields higher-quality results for complex fixes.

User: "Please fix Sentry issue ABC-123."

Agent: -> red_analyze_error({ sentry_issue_id: "ABC-123" })
  -> Review the suggested_fix in the response.
  -> red_generate_fix_pr({
       sentry_issue_id: "ABC-123",
       use_purple_chain: true   // High-quality mode
     })
  -> PR URL: https://github.com/Corevice/.../pull/512

C. AI-generated and AI-executed E2E tests — Blue Codens

Generate E2E test scenarios automatically from a PRD or issue, and run them in coordination with CI. When tests fail, the trace can be passed to Red Codens for an automated fix.

User: "Add E2E tests for the checkout flow in green-codens."

Agent: -> blue_generate_e2e_tests({
    repo: "Corevice/green-codens",
    feature: "checkout-flow",
    framework: "playwright"
  })
  -> blue_run_e2e({ test_suite_id })
  -> Response: { passed: 12, failed: 0, video_url, trace_url }

D. From conversation to PRD to implementation — Green into Purple

Green Codens shapes vague requests into a structured PRD, and the same PRD is handed to Purple Codens for automated implementation. Notion synchronization is enabled by default.

User: "Add an annual plan option to the billing screen. Please handle requirements gathering and implementation."

Agent: -> green_prd_create({
    title: "Annual plan selection UI",
    raw_input: "Add an annual plan option to the billing screen..."
  })
  -> green_prd_finalize({ prd_id })  // The AI structures the requirements.
  -> purple_workflow_create({
       repo: "Corevice/billing-control-plane",
       prd_id,
       base_branch: "develop"
     })
  -> Share the PR URL with the user once the workflow completes.

4. The full catalog of 30 tools

The list below covers every tool offered by the Codens family. Once the MCP server is enabled, all of them are directly callable from an agent.

Purple Codens (16 tools) — AI development orchestration

Tool	Description
`codens_login`	Sign in to Codens via Device Code Flow (enter the `user_code` at `auth.codens.ai/device`). Token is stored in the secure store.
`purple_logout`	Discard the stored token.
`purple_whoami`	Return the current user, organization, and remaining credit.
`purple_workflow_create`	Create a new workflow (task) and start execution on a VPS.
`purple_workflow_status`	Retrieve the workflow's current step, progress, and remaining time.
`purple_workflow_list`	List the organization's workflows, filterable by status, repository, and creation time.
`purple_workflow_logs`	Fetch execution logs for a workflow as a stream or batch.
`purple_workflow_cancel`	Stop a running workflow.
`purple_workflow_retry`	Resume from the failed step. Useful after the underlying cause has been corrected.
`purple_task_create`	Create a single task within a workflow directly (for manual breakdowns).
`purple_task_attach_file`	Attach additional context (PRD, specification) to a task.
`purple_repo_register`	Register a new repository with the Codens project, including the useWorktree setting.
`purple_repo_list`	Return the list of registered repositories.
`purple_credit_balance`	Return the credit balance, the consumption over the past 7 days, and the next reset.
`purple_credit_grant`	(Admin) Grant credits to an arbitrary organization.
`purple_billing_portal_url`	Return a signed URL to the Stripe Customer Portal.

Red Codens (4 tools) — error detection and automated fix PRs

Tool	Description
`red_analyze_error`	Analyze a Sentry issue or stack trace and return the root cause and a fix plan.
`red_generate_fix_pr`	Generate the fix PR automatically. Setting `use_purple_chain` enables high-quality mode.
`red_list_recent_fixes`	Return the recent automated fix PRs and their merge status.
`red_run_3retry_loop`	Retry up to three times, feeding test results back into the prompt.

Blue Codens (4 tools) — QA automation

Tool	Description
`blue_generate_unit_tests`	Automatically generate unit tests for a given module or function.
`blue_generate_e2e_tests`	Automatically generate E2E test scenarios from a feature or PRD (Playwright or Cypress).
`blue_run_e2e`	Execute an E2E test suite and return video, trace, and network logs.
`blue_analyze_failure`	Analyze a failing trace and return a report that can be chained into Red Codens.

Green Codens (4 tools) — PRD creation and management

Tool	Description
`green_prd_create`	Create a draft PRD from raw input (Claude structures the content).
`green_prd_finalize`	Finalize the draft and synchronize it to Notion or a GitHub Issue.
`green_prd_list`	List PRDs (filterable by status, owner, and related repository).
`green_prd_link_workflow`	Link a PRD to a Purple workflow and synchronize progress in both directions.

Auth Codens (2 tools) — authentication and organization management

Tool	Description
`auth_token_refresh`	Refresh the access token. Useful for renewing it before it expires.
`auth_org_switch`	Switch the active organization for users who belong to multiple organizations.

Total: Purple 16 + Red 4 + Blue 4 + Green 4 + Auth 2 = 30 tools.

5. Error envelope

Every REST and MCP endpoint returns errors in a common envelope. The error_code field is a machine-readable enum that an agent can use to decide whether to retry or fall back.

Common error format

{
  "ok": false,
  "error_code": "RATE_LIMITED",
  "message": "Rate limit exceeded for org_01H... (30 req/min)",
  "details": { "retry_after_seconds": 12, "limit": 30 },
  "trace_id": "trc_01H...",
  "retryable": true
}

The nine `error_code` enum values and their retry semantics

error_code	Meaning	Retry semantics
`RATE_LIMITED`	The rate limit was exceeded. Respect `details.retry_after_seconds`.	retryable: true (with exponential backoff)
`BUDGET_EXCEEDED`	The organization's monthly budget cap has been reached. Increase it via `purple_billing_portal_url`.	retryable: false
`CREDIT_INSUFFICIENT`	The credit balance is insufficient. Confirm the balance with `purple_credit_balance`.	retryable: false
`WORKFLOW_NOT_FOUND`	The specified workflow_id does not exist or is owned by a different organization.	retryable: false
`UNAUTHORIZED`	The token is invalid or has expired. Retry after calling `auth_token_refresh`.	retryable: true (after refresh)
`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD`	The same Idempotency-Key was sent again with a different payload.	retryable: false
`INTERNAL_ERROR`	An unexpected server-side error. Contact support with the trace_id.	retryable: true (with a short backoff)
`VALIDATION_ERROR`	The request body or query parameters failed validation.	retryable: false
`RESOURCE_NOT_FOUND`	The target resource (repository, PRD, task, etc.) does not exist.	retryable: false

Operating with Idempotency-Key

Write endpoints that create workflows or pull requests require the Idempotency-Key header. The same key paired with the same payload returns the same result; if the payload differs, the request is rejected with IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD.

6. Pricing

Codens uses a hybrid model that combines prepaid credits and usage-based billing. For details, please refer to the Pricing page. Agents that need a machine-readable view should call the endpoint below.

Machine-readable pricing endpoint

GET https://api.purple.codens.ai/v1/public/pricing
Accept: application/json

// Response
{
  "currency": "JPY",
  "plans": [
    { "id": "starter",      "monthly_credit_jpy":   3000, "price_jpy":   3000 },
    { "id": "pro",          "monthly_credit_jpy":  30000, "price_jpy":  25000 },
    { "id": "team",         "monthly_credit_jpy": 150000, "price_jpy": 120000 }
  ],
  "metering": [
    { "tool_prefix": "purple_workflow_*", "unit": "minute_compute", "price_jpy": 5 },
    { "tool_prefix": "red_*",             "unit": "fix_attempt",    "price_jpy": 30 },
    { "tool_prefix": "blue_*",            "unit": "test_run",       "price_jpy": 10 },
    { "tool_prefix": "green_*",           "unit": "prd_finalize",   "price_jpy": 20 }
  ],
  "default_grant_on_signup_jpy": 1000
}

New organizations receive an automatic credit grant of 1,000 JPY on first signup. Onboarding via the planned Stripe Projects auto-signup will offer an additional bonus.

7. Troubleshooting

The table below lists common symptoms and points to check. If the issue is not resolved, please reach out via the Contact page and include the trace_id.

Symptom	What to verify
The MCP tools are not visible to the agent.	Confirm that `mcpServers.codens.command` in `~/.claude/settings.json` points to the absolute path of the installed `codens-mcp` binary. Please share the output of `which codens-mcp` when reporting the issue.
`expired_token` blocks login	The Device Code Flow `user_code` is valid for about 5 minutes. Open https://auth.codens.ai/device immediately after the tool prints the code. If you keep failing, open the URL before calling `codens_login` and paste the code as soon as it appears. A fresh code is issued every time you call the tool.
`UNAUTHORIZED` errors are returned repeatedly.	The token has likely expired. Run `codens_login` again, or include `auth_token_refresh` in the agent flow.
The workflow stays in "pending" and does not start.	The VPS pool may be saturated. Check `queue_position` in the `purple_workflow_status` response. If progress remains stalled for more than 15 minutes, contact us with the trace_id.
Credits are consumed faster than expected.	Inspect `recent_consumption` in the `purple_credit_balance` response. Identify the heaviest tools through `tool_breakdown` and, if necessary, throttle them with `purple_workflow_cancel`.
A pull request is created, but tests are failing.	Use `red_run_3retry_loop` to feed the test results back and retry the fix up to three times. If the tests still fail, run `blue_analyze_failure` to identify the root cause.
Notion synchronization (Green) is not reflected.	Verify whether the organization's Notion integration is enabled by checking `sync_status` in the `green_prd_list` response. If the value is `integration_disabled`, an administrator must review the integration in Auth Codens.

8. References

For deeper information, please follow the links below.

PyPI: codens-mcp — Unified MCP server (all 30 tools across Red / Blue / Green / Auth + Purple).
PyPI: purple-codens-mcp — Purple-only MCP (dependency of codens-mcp; usable standalone).
Pricing plans — Five tiers (1 credit = ¥0.01).
Pricing JSON (machine-readable) — Fetchable directly from agents (initial credit grant and per-tier rates).
OIDC Discovery — Auth metadata for the Codens family.
Codens Dashboard — Customer console (organization / project / billing settings).
Contact — Feature requests, bug reports, or sales inquiries.