cran-mcp

Model Context Protocol server for Cran — drive LLM audits from Claude Code, Cursor, Windsurf, Continue.dev, Zed, and any MCP-aware AI client.

Cran benchmarks the LLM models your product actually uses against alternatives and tells you which to ship. This MCP server is the IDE-side bridge: your AI agent walks your repo locally, discovers every LLM call site, registers them with Cran, runs faithful audits, and reports back routing recommendations — without your source code ever leaving your machine.

Full audit docs: https://trycran.in/docs/audits

Install

Preferred: Cran CLI

npm i -g @findyourmodel/cran
cran login                # browser sign-in, once per machine
cran mcp install cursor   # or claude, windsurf, etc.

Connect once and you're done. After cran login, "use Cran" works in any repo on your account's default project — no per-repo cran link, no .cran/config.toml, no per-repo token. Auth comes from ~/.cran/session.json — no manual token paste.

cran link is optional — only needed to route your app's live traffic through the Cran proxy (it writes a connection key to .env). It is not a prerequisite for the MCP, scan, or audit.

Manual MCP config

{
  "mcpServers": {
    "cran": {
      "command": "npx",
      "args": ["-y", "cran-mcp"],
      "env": {
        "FYM_API_KEY": "fym_xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart your MCP client. All fym_* tools appear in the tool palette.

"Use Cran" playbook (agent onboarding)

The MCP connection is your account login. Once the user has run cran login, "use Cran" works in any repo against their account's default project — there is no per-repo link step.

When the user says use Cran:

1. Call fym_connect (or fym_onboard) — read the status field in the JSON payload.
2. needs_login → ask the user to run cran login once in a terminal.
3. Logged in → you're on the default project. To work somewhere else, switch the active project with fym_use_project (or create one with fym_ensure_project).
4. To register a repo's call sites, run fym_scan_codebase (local — source never leaves the machine) then fym_submit_manifest, and audit from there.

Routing live traffic is separate and optional. Only when you want the user's app to call models through the Cran proxy do you call fym_link_repo — it mints a connection key into .env so OPENAI_API_KEY + OPENAI_BASE_URL point at Cran with model: "auto". This is not needed for the MCP, scan, or audit.

Supporting tools: fym_list_teams, fym_list_projects, fym_use_project, fym_ensure_project, fym_link_repo (optional, routing).

Tools (23)

| Tool | Category | What it does | |---|---|---| | fym_connect | connect | Onboarding entry — assess account/project state; wire env when routing is linked. | | fym_onboard | connect | Same assessment as fym_connect when the repo is not routing-linked yet. | | fym_list_teams | connect | Teams/workspaces the user belongs to. | | fym_list_projects | connect | Dashboard products under a team. | | fym_use_project | connect | Switch the active project for this session (default project otherwise). | | fym_ensure_project | connect | Create or find a product under a team (no local link files). | | fym_link_repo | connect · optional, routing | Mint a connection key + write .env to route this app's live traffic through the proxy. Not needed for the MCP/scan/audit. | | fym_list_models | catalog | Model catalog with prices. No auth. | | fym_get_manifest_schema | onboarding | Manifest JSON Schema + privacy rules. | | fym_scan_codebase | onboarding · local | Discover LLM call sites on this machine. Source never uploaded. | | fym_submit_manifest | onboarding | Register workflows from completed manifest. | | fym_list_workflows | audit | List workflows with status + last score. | | fym_get_workflow | audit | Full workflow record (prompt, tools, config). | | fym_classify_workflow | audit | Auto-detect class + judge strategy. | | fym_generate_test_suite | audit | Adversarial stress-test prompts (cached). | | fym_run_audit | audit | Faithful benchmark — workflow or ad-hoc mode. | | fym_list_audits | audit | List recent audits for this project. | | fym_get_audit | audit | Reload audit by ID (normalized camelCase). | | fym_get_routing_policy | audit | Export deployable routing code. | | fym_propose_change | proposals | Submit change for human approval. | | fym_list_pending_proposals | proposals | Poll proposal status. | | fym_apply_proposal | proposals | Mark approved proposal as applied. | | fym_run_architecture_audit | intelligence | Cross-workflow architecture review. | | fym_get_limits / fym_set_limits | limits | Read/update proxy rate + spend caps. |

Audit workflow (recommended)

1. fym_get_manifest_schema()
2. fym_scan_codebase()              ← walks your repo locally
3. (agent reads files, builds manifest)
4. fym_submit_manifest({ manifest })
5. fym_list_workflows()
6. Per workflow:
     fym_classify_workflow({ slugOrId })
     fym_generate_test_suite({ slugOrId })
     fym_run_audit({ workflowId, useGeneratedTests: true })
7. fym_get_routing_policy({ auditId, format: "vercel-ai-sdk" })
8. fym_propose_change({ ... })      ← human approves in dashboard

fym_run_audit modes

Workflow mode — pass workflowId (slug or DB id):

• Inherits system_prompt, judge_strategy, params, tools from the workflow
• Prompts from useGeneratedTests: true (recommended), sample_inputs, or extraPrompts
• Models auto-picked: baseline + cross-provider alternatives (cap 4) unless models is set

Ad-hoc mode — pass prompts + models:

• No workflow inheritance; for one-off experiments

Overrides (both modes): judgeStrategy, judgeModel, params, tools, tool_choice

Response shape

{
  "audit_id": "aud_…",
  "workflow_id": "wf_…",
  "cells": [{ "promptId", "modelId", "output", "judgment": { "score": 4, "rationale": "…" }, ... }],
  "perModel": [{ "modelId", "avgScore", "p50LatencyMs", "p95LatencyMs", "totalCostUsd", ... }],
  "recommendation": { "primary", "fallbacks", "costRoute", "reason" }
}

See https://trycran.in/docs/audits for the full contract.

Environment variables

| Variable | Required | Default | Purpose | |---|---|---|---| | FYM_API_KEY | For writes | from cran login | Bearer token (fym_…) | | FYM_API_BASE_URL | No | https://trycran.in | API host (use http://localhost:3000 locally) | | FYM_CRAN_PROJECT | No | from .cran/config.toml | Project header for CLI tokens |

Security

• Source code never leaves the user's machine. fym_scan_codebase runs locally and returns only file paths + SDK hints.
• Provider API keys live server-side. The MCP server holds only the Cran agent token.
• Tokens are project-scoped and hashed at rest.
• Default scopes: read + propose. fym_set_limits and fym_apply_proposal need apply.

Development

npm run build:mcp
FYM_API_BASE_URL=http://localhost:3000 FYM_API_KEY=fym_xxxx \
  node packages/mcp/dist/index.js

npm run inspect   # MCP Inspector UI