@intencion/mcp

@intencion/mcp

An MCP server that lets your coding agent — Claude Code, Cursor — debug a bad AI-agent run from your editor. Ask "why did my agent fail?" and the agent queries your Intencion run data and walks you to the root cause, with evidence.

It's a thin, read-only client over the Intencion read API. No database access, no writes — just your captured runs, in the editor where you'd fix them.

What it does

A developer hits a bad run and asks their editor what happened. The agent walks the debugging journey on its own:

"why is my agent failing?"
  → get_success_rate        how bad, and when did it start?
  → list_intents            which goal is dragging the rate down?
  → list_failure_modes      what's the pattern, which step errors most, how widespread?
  → list_runs               concrete failing example runs
  → diagnose_run            the failing step + its exact error + model-vs-data hint + blast radius
  → get_session / get_trace did the user re-ask? did a sub-agent run cascade up?

Every answer is evidence-first: literal error strings and tool I/O are quoted verbatim, fields are tagged recorded (from your telemetry) vs derived (computed), and the server never invents a cause it can't show you.

Install

Claude Code

claude mcp add intencion --env INTENCION_API_KEY=in_pk_xxx -- npx -y @intencion/mcp

Cursor / generic mcpServers JSON

{
  "mcpServers": {
    "intencion": {
      "command": "npx",
      "args": ["-y", "@intencion/mcp"],
      "env": { "INTENCION_API_KEY": "in_pk_..." }
    }
  }
}

Configuration

Variable	Required	Default	Notes
INTENCION_API_KEY	yes	—	Your Intencion key (starts with in_pk_). The server exits at startup if it's missing.
INTENCION_BASE_URL	no	https://intencion.io	Point at a self-hosted / dev instance if needed.

The key scopes every request to one workspace; the server only ever reads.

Tools

Tool	Use it when	Args
get_success_rate	"Is my agent OK? When did it break?" — triage.	range?
compare_windows	"What changed after my deploy?" — before/after a boundary time.	boundary, intent?, window?
list_intents	"What's it failing at?" — the map of goals + success rates.	range?
list_failure_modes	One intent's failure patterns, blast radius, and worst step.	intent, range?
list_runs	Find example runs — outcome:"failure" or silent:true.	intent?, outcome?, range?, limit?, silent?
get_run	The full timeline of one run, incl. tool I/O.	run_id
list_sessions	Discover recent conversations to inspect.	(none)
diagnose_run	Why did this run fail? Failing step + error + model-vs-data hint + blast radius.	run_id
get_session	The conversation around a run — confirm a re-ask.	session_id
get_trace	The causal sub-agent tree — did a child run cascade up?	trace_id

Every required id is discoverable from a prior tool's output, so the agent can start from a plain question and never needs an id you'd have to look up by hand.

Example

You: my order-status agent keeps failing — why?

Agent (calls list_intents → list_failure_modes {intent: "order_status"} → list_runs {intent: "order_status", outcome: "failure"} → diagnose_run {run_id}): The order_status intent is at 50% success. The failures cluster on the lookup_order step — it errored in N runs this week. Example run …: it failed at lookup_order (orders-db) with "No order found with ID Z9999." That's a data/tool-path failure, not a model mistake — the lookup couldn't find the order. It's hit N runs / M users, so it's a pattern, not a one-off.

Privacy

Read-only. The server makes authenticated GET requests to the Intencion read API with your key and returns the results to your agent. It has no database access and never writes.

Be aware of what it surfaces: by default the Intencion SDKs capture full run content, and this server exposes it to the model driving your editor. That includes the prompt and reply text, tool-call inputs/outputs, and the request context the model ran with (system prompt, tool definitions, sampling params). All of it is PII- and secret-redacted before storage, but it is still your agents' content, so use this server where sending that to your coding assistant is acceptable. To collect less in the first place, set captureContent: false (metadata-only) in the SDK. See the data-collection reference at https://intencion.io/docs for exactly what is and isn't collected and how to control it.

License

MIT