Platform

Agent protocol

The single reference for Claude Code, Cursor, Codex, and any tool that builds or operates a product on Cran: connection, runtime endpoints, changing model/prompt/params on the platform (not just in app code), deployment, and the MCP tool surface.

Lifecycle overview

text

Developer / agent                    Cran platform
─────────────────                    ─────────────
cran login   ─────────────────────►  device auth → account session (connects MCP)
cran mcp install <ide>  ──────────►  IDE agent can drive Cran
"use cran" in any repo  ──────────►  works on your default project
cran_scan + submit manifest  ─────►  workflows registered
cran_run_audit  ──────────────────►  compare models, scores
human publishes architecture  ────►  model, system_prompt, params
cran link (optional)  ────────────►  mint connection key for live traffic
app uses model:"auto" + env vars ─►  POST /api/v1/chat/completions

1 - Connect the account

Connect once - no per-project link, no per-repo token:

bash

npm i -g cran-cli
cran login               # browser → ~/.cran/session.json (the MCP connection)
cran mcp install cursor  # IDE MCP (runs cran mcp run)

With MCP, call cran_connect when the user says “use Cran”; it returns account_readywith the default project active. From there, “use cran” works in any repo on your account. Switch projects with cran_use_project. Linking a repo (cran_link_repo or cran link) is optional and only routes live traffic - see step 4.

2 - Runtime proxy

Drop-in OpenAI-compatible API. Point any SDK at Cran instead of OpenAI:

http

POST https://trycran.in/api/v1/chat/completions
Authorization: Bearer cran_CONNECTION_TOKEN
Content-Type: application/json

{ "model": "auto", "messages": [{ "role": "user", "content": "Hello" }] }

model resolves as: "auto" → published architecture (smart fallback if none); a workflow slug → that workflow’s architecture; a catalog id → direct, unmanaged. Optional x-cran-route: cost selects the cost route.

3 - Platform control

Users change AI behavior from the dashboard, not only in app code. Each registered workflow can carry a managed architecture the proxy applies at runtime when published - model + fallbacks + cost route, system prompt, params, tools, and response format.

json

{
  "model": "anthropic/claude-haiku-4-5",
  "fallbacks": ["openai/gpt-5.4"],
  "cost_route": "google/gemini-2.5-flash-lite",
  "params": { "temperature": 0, "max_tokens": 512, "top_p": 1 },
  "system_prompt": "You are a refund classifier…",
  "tools": [],
  "response_format": { "type": "json_object" }
}

4 - Deploy to production (live-traffic routing)

Only relevant once you route live traffic through the proxy. Cran isn’t installed on your server - copy the same env vars from local .env into your host:

.env

OPENAI_API_KEY=cran_…    # connection key from cran link (routing only)
OPENAI_BASE_URL=https://trycran.in/api/v1
CRAN_PROJECT_ID=project_…

Never commit .env; never deploy the user CLI session token; use separate projects/keys for staging vs production. See Deployment.

5 - Scan, audit, propose

cran_get_manifest_schema → cran_scan_codebase - find call sites locally.
Build the manifest → cran_submit_manifest.
cran_classify_workflow + cran_generate_test_suite per workflow.
cran_run_audit with useGeneratedTests: true.
cran_propose_change → human approves → cran_apply_proposal → publish.

Full audit shapes and judge strategies: Audits.

MCP tools

Tool	When to use
cran_connect	User says “use Cran” - confirms the account session; returns account_ready (default project active, no link needed).
cran_onboard	Like cran_connect - structured status JSON for the connected account.
cran_use_project	Switch the active project for this session.
cran_list_teams	User belongs to multiple teams - list before switching/creating.
cran_list_projects	List products under a chosen team.
cran_ensure_project	Create/find a product (no local files written).
cran_link_repo	OPTIONAL - only to route live traffic: mint a connection key and write .cran/config.toml + .env.
cran_list_models	Catalog ids and pricing (no auth).
cran_get_manifest_schema	Before scanning - manifest shape and privacy rules.
cran_scan_codebase	Discover LLM call sites locally (source never uploaded).
cran_submit_manifest	Register workflows from a completed manifest (propose scope).
cran_list_workflows	List registered workflows and audit status.
cran_get_workflow	Read prompt, tools, schema, current config for one workflow.
cran_classify_workflow	Auto-detect workflow class + judge strategy.
cran_generate_test_suite	Stress-test prompts for a workflow.
cran_run_audit	Benchmark prompts × models with faithful config; get a recommendation.
cran_get_audit	Reload a past audit by id (normalized shape).
cran_get_routing_policy	Export deployable routing code from an audit.
cran_propose_change	Submit a model/prompt/routing change for human approval.
cran_apply_proposal	Apply a human-approved proposal (apply scope).
cran_run_architecture_audit	Cross-workflow architecture review.
cran_get_limits / cran_set_limits	Read / update project rate limits and spend caps.

Tokens & headers

Connection key (cran_…) - optional, from cran link; in app OPENAI_API_KEY to route live traffic; fixed project on the row.
User CLI session token - from cran login; this is the MCP connection. Project is null, so send X-Cran-Project: <id|slug> for project-scoped API routes.
x-cran-route: cost - selects the published cost route.

REST details (audits, workflows, CLI device auth, limits): API reference.