Connect Ella to your tools with MCP

coderetro speaks the Model Context Protocol. Any MCP client can ask Ella about your code, record what an agent changed, run a confidence check, or investigate a production error.

coderetro is in early access. The local server below ships with the CLI today. The hosted server is planned for early-access users, and its tool names and fields may change before general availability. Join the waitlist to get access.

Overview

There are two servers. Use the local one inside a repository, and the hosted one anywhere else.

Server	Runs	Best for	Status
Local	`coderetro mcp` on your machine, over stdio, in the repo's folder	Coding agents: context before edits, recording changes, checks before a deploy	Available in early access
Hosted	`https://mcp.coderetro.ai/mcp`, over Streamable HTTP	Workflows without a checkout: CI jobs, on-call bots, Claude Desktop, team tools	Planned

In the examples, @eric is a developer and @ella is coderetro. Your agent doesn't need the name: asking "what changed in billing?" works too. Mentioning Ella just makes it obvious which tool you want.

Local server setup

Install the CLI once per computer, sign in, and connect the repo:

npm install -g @coderetro/local
coderetro login                      # approve this computer in the browser
cd path/to/repo
coderetro init --cloud --agents      # or --local-only to keep everything on this machine

--agents adds a short section to CLAUDE.md and AGENTS.md telling agents when to call the tools.

Claude Code

The plugin registers the MCP server and adds the slash commands /coderetro:retro, /coderetro:brief and /coderetro:check. It also records a change automatically when a session ends.

/plugin marketplace add coderetroai/cr-local
/plugin install coderetro@coderetro

MCP server only, without the plugin:

claude mcp add coderetro -- coderetro mcp

Cursor

Add to .cursor/mcp.json in the repo, or to ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "coderetro": { "command": "coderetro", "args": ["mcp"] }
  }
}

If Cursor can't find coderetro (common with nvm), use "command": "npx", "args": ["-y", "@coderetro/local", "mcp"].

Codex

Add to ~/.codex/config.toml:

[mcp_servers.coderetro]
command = "coderetro"
args = ["mcp"]

Any other MCP client

Start coderetro mcp as a stdio server with the repository as its working directory. It reads the repo's .coderetro/config.json and your saved sign-in.

Hosted server setup Planned

The hosted server answers from your account's cloud history, so it works without a checkout of the code. You sign in with your coderetro account the first time a client connects.

# Claude Code
claude mcp add --transport http coderetro https://mcp.coderetro.ai/mcp

# Cursor (.cursor/mcp.json)
{ "mcpServers": { "coderetro": { "url": "https://mcp.coderetro.ai/mcp" } } }

# Claude Desktop and claude.ai: Settings, Connectors, Add custom connector
https://mcp.coderetro.ai/mcp

For headless clients such as CI jobs and bots, send a personal API token instead of signing in interactively: Authorization: Bearer cra_…. Create one in the web app under Account, Tokens.

Local tools

These are the tools coderetro mcp exposes today. Only record_change writes anything.

`get_context`

Call before editing a file or folder you don't know well. Returns markdown: what the area does, what depends on it, recent changes and their reasons, assumptions that must keep holding, known risks and open issues.

Field	Type	Description
`path`	string, required	Repo-relative file or folder, for example `app/api/webhooks/stripe/route.ts`. Use `.` for the whole app.

`record_change`

Call once at the end of each meaningful unit of work. Git facts (files, line counts, branch, commits) are collected automatically; the agent supplies the reasoning. Secrets and email addresses are redacted before anything is stored. Returns the digest id and a one-line recap.

Field	Type	Description
`intent`	string, required	What the change is for, in one sentence (up to 500 characters).
`kind`	enum	`feature`, `bugfix`, `refactor`, `dependency`, `config`, `test`, `docs`, `revert`, `other`. Inferred from the files when omitted.
`trigger`, `trigger_ref`	enum, string	What prompted the work (`user_request`, `bug_report`, `incident`, `test_failure`, `review`, `dependency_update`, `other`) and a ticket or incident reference.
`root_cause`	string	For fixes: the underlying cause, not the symptom.
`approach`	string	How it was solved and the key design decision.
`alternatives_rejected`	array of `{option, why}`	Options considered and why they weren't picked.
`assumptions`	string[]	Things the change relies on staying true.
`risks`	array of `{description, severity}`	What might break; severity is `low`, `medium` or `high`.
`follow_ups`, `concepts`	string[]	Work left undone; technical concepts the change relies on.
`tests`	object	`{added, ran, passed}`; `ran` is `none`, `unit`, `integration`, `e2e` or `manual`.
`confidence`	enum	`low`, `medium` or `high`: how sure the agent is this works in production.
`base`, `files`	string, string[]	The git ref the work started from, and an optional list of paths to limit the record to.
`session_id`, `tool`, `model`	string	The agent's session id (prevents a duplicate automatic record), its name and model.

`run_check`

Scans the repo on your machine for production risks: hardcoded or browser-exposed secrets, committed .env files, API routes that touch data without an auth check, unverified or repeat-unsafe Stripe webhooks, missing rate limits, destructive migrations and unhandled external calls. Returns findings with file:line evidence, a fix prompt for each, and what it didn't check. Sends nothing anywhere.

Field	Type	Description
`min_severity`	enum	Only return findings at or above `low`, `medium`, `high` or `critical`.

`investigate_error`

Maps a stack trace to files in the repo, finds recent changes that touched them with their assumptions and risks, and returns a likely cause with a confidence level and a fix prompt. Uses the cloud when connected and works locally otherwise. The message and stack are redacted before they leave your machine.

Field	Type	Description
`message`	string, required	The error message.
`stack`	string	The full stack trace, if you have it. Without one, the answer is a low-confidence guess and says so.

`get_app_overview`

A plain-language map of the app: stack, API routes and whether each checks auth, external services, database tables and environment variable names. Useful before planning a change.

Field	Type	Description
`refresh`	boolean	Rescan the repo instead of using the last snapshot.

What it looks like in an agent

> @ella why does the Stripe webhook write to stripe_events?

  coderetro.get_context(path: "app/api/webhooks/stripe/route.ts")

Ella: Added Oct 1 by Claude Code to stop duplicate charges. Stripe retries
slow webhooks, and the old handler captured the payment on every retry.
It assumes event ids are unique. The refunds handler still has the old
pattern, so a slow refund webhook can refund twice.

Hosted tools Planned

The hosted server works across projects, so every tool takes a project (its slug, like acme/shopfront, or its id). The token you connect with decides which projects you can see.

Tool	Inputs	Returns
`list_projects`	none	Projects in your account and teams
`get_context`	`project`, `path`	The same briefing as the local tool, from cloud history
`list_changes`	`project`, `path?`, `since?`, `limit?`	Recent changes with their recaps, newest first
`get_app_map`	`project`	The App Map: parts of the app, what each does, how they connect
`get_findings`	`project`, `min_severity?`	Open confidence-check findings, the score, and what wasn't checked
`get_patterns`	`project`, `status?`	Recurring issues with a suggested rule for your agents
`investigate_error`	`project`, `message`, `stack?`	Failing path, related changes, likely cause and a fix prompt
`ask`	`project`, `question`	Ella's answer in prose, with the changes and files it's based on

Workflow recipes

Make your agent check before it edits

Put this in CLAUDE.md or AGENTS.md (coderetro init --agents writes a version of it for you):

## coderetro
- Before editing files you haven't read in this session, call `get_context` with their path.
- When you finish a feature, fix or refactor, call `record_change` once. Include the root
  cause, the approach, options you rejected, assumptions and risks. Be candid about risks.
- Before saying a change is ready to deploy, call `run_check` with min_severity "high".

Debug a production error from your editor

Paste the error and stack into your agent and mention Ella. The agent calls investigate_error, then works from the fix prompt with the right files already in view.

> @ella investigate this from Sentry, then fix it with a failing test first:
  TypeError: Cannot read properties of null (reading 'user_id')
      at GET (app/api/orders/route.ts:14:31)

Explain every pull request Planned

A CI job connects an agent to the hosted server with a personal token, calls list_changes for the files in the pull request, and posts Ella's summary as a comment: what changed, why, what it assumes and what to test.

Build your own on-call or team bot Planned

Any MCP-capable agent framework can connect to https://mcp.coderetro.ai/mcp with a bearer token. Route questions like @ella what broke checkout? from your chat tool to the ask or investigate_error tool, and post the answer back.

Auth and privacy

Local server: uses the sign-in saved by coderetro login in ~/.coderetro (readable only by you), or a project token in CODERETRO_TOKEN for CI. In local-only mode it never makes a network call.
Hosted server: signs you in with OAuth the first time a client connects. Headless clients send a personal API token. Revoke either in the web app at any time.
Redaction: secrets, tokens, credentials in URLs and email addresses are replaced before anything leaves your machine. Source code isn't sent unless you turn on snippets for the project.
Access: a token sees only the projects in its account. Team members see a team's projects; nobody sees your personal account.

Errors and limits

Tool failures come back as MCP errors (isError: true) with a plain message that starts with what couldn't be done, for example coderetro couldn't get context: …. The CLI's log in ~/.coderetro/logs has the details.
If the cloud is unreachable, record_change queues the change and sends it on the next sync. Nothing is lost.
The hosted server will rate-limit per token. A limited call returns an error with how long to wait.

Questions or a workflow you want supported? Tell us when you join the waitlist, or open an issue on GitHub.