Ace MCP server

The Ace MCP server gives any Model Context Protocol client read access to what Ace knows about your incidents, so the agent that changes your code can see what happened in production, what was tried before and how your team wants the work done.

All tools are read-only, and the server can't change anything in Ace or in your systems. Ace changes live systems only through its own actions, under your approval policy.

Common uses:

• A coding agent loads an incident's root cause, evidence and proposed actions before it opens a pull request.
• A reviewer checks whether a change repeats a fix that made a similar incident worse.
• Agents read your operating rules before they diagnose or change anything.
• You check a workload's open incidents, early warnings and recent changes before a deploy.

Before you startCopy Anchor Link

• Creating a token needs the admin role, because a token reads your whole organization. See Roles and permissions.
• Your MCP client must support remote servers over Streamable HTTP with a custom Authorization header. For stdio-only clients, use the mcp-remote bridge under Other clients in Step 2.
• Ace authenticates with access tokens, so skip any OAuth sign-in your client offers for this server.

Step 1: Create a tokenCopy Anchor Link

1. In Ace, open Settings > MCP.
2. Under Create a token, name the token after its use, such as Claude Code - payments repo.
3. Choose when it expires: in 30, 90 (the default), 180 or 365 days.
4. Select Create token.
5. Copy the token now, because Ace shows it once and stores only a hash. Tokens start with ace_mcp_.

Store the token as an environment variable in your shell profile or secret manager, then reference the variable in your client's configuration so the token stays out of config files:

export ACE_MCP_TOKEN="ace_mcp_..."

Step 2: Connect your clientCopy Anchor Link

{
  "mcpServers": {
    "ace": {
      "type": "http",
      "url": "https://app.tryace.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${ACE_MCP_TOKEN}"
      }
    }
  }
}

claude mcp add --transport http ace https://app.tryace.dev/api/mcp --header 'Authorization: Bearer ${ACE_MCP_TOKEN}'

ToolsCopy Anchor Link

Pass an incident as its Ace reference, such as INS-1018-ab12, or its ID, and a workload as its name or ID. Lookups only see your organization.

get_incident_contextCopy Anchor Link

Returns the full incident as Markdown and as structured data, including:

• headline, workload, severity, status and a link to the incident
• what happened and what triggered it
• the root cause with its confidence, supporting and contradicting evidence, and open questions
• the evidence timeline, with source links where available
• matched services and the dependency path, when known
• notes from Ace and your engineers
• every proposed or running action, with its progress, constraints and pull request link

{ "incident": "INS-1018-ab12" }

search_incidentsCopy Anchor Link

Finds incidents by meaning and by text in the headline, reference or workload name. Matches by meaning come first with a similarity score, followed by the most recent text matches with severity and status. Each result includes the reference to pass to get_incident_context.

Without query, it lists the most recent incidents. status defaults to any and limit defaults to 10.

{ "query": "orders stuck after a schema migration", "status": "resolved", "limit": 5 }

get_lessonsCopy Anchor Link

Returns what Ace learned from verified outcomes. Pass at least one of incident, query or workload, and limit defaults to 5. The result has three parts:

• Fixes that worked lists fixes that recovered the workload and never made it worse, with counts.
• Fixes to avoid lists fixes that made an incident worse, or that failed to recover the workload at least twice and never recovered it.
• Similar past incidents, with the actions Ace took in each and how each was judged.

Fix history needs a workload, because Ace tracks fixes per workload. It takes the workload from workload, or from the workload of incident. See How memory works.

{ "workload": "checkout-api", "query": "p99 latency spike after deploy" }

get_operating_rulesCopy Anchor Link

Returns your workspace's operating rules and the kinds of work each one covers. applies_to filters to one kind of work, and rules that apply to everything are always included.

{ "applies_to": "code_change" }

get_workload_contextCopy Anchor Link

Returns a workload's open incidents and open early warnings, where each early warning is a forecast or a capacity risk with when the limit is expected to be hit. The result also lists up to 20 changes from the last 24 hours, such as deploys and configuration or infrastructure changes.

{ "workload": "checkout-api" }

Example promptsCopy Anchor Link

Each prompt lists the tools it should call, though most clients pick tools on their own once Ace is connected.

Fix an incident with full context

Load Ace incident INS-1018-ab12 and our operating rules for pull requests.
Then fix the root cause in this repository. Don't repeat any fix that Ace
lists under "Fixes to avoid" for this incident's workload.

Tools: get_incident_context, get_operating_rules with applies_to: "code_change", get_lessons with incident.

Review a pull request against past incidents

Review this diff. Use Ace to find past incidents on checkout-api that touched the
same code path, and flag anything this change repeats from a fix that made an
incident worse or didn't recover it.

Tools: search_incidents, get_lessons with workload.

Check a workload before you deploy

Before I deploy payments-worker, check Ace for open incidents, early warnings and
changes in the last day. Tell me if anything argues for waiting.

Tools: get_workload_context.

Write a post-incident summary

Summarize Ace incident INS-1018-ab12 for our incident review: what happened, the
root cause with its evidence, what was changed, and what's still unknown.

Tools: get_incident_context.

Security and accessCopy Anchor Link

• All five tools are marked read-only in their MCP annotations.
• A token belongs to the organization and reads all of its incidents, workloads and rules, whoever created it. Only admins can create, see and revoke tokens.
• Ace stores only a hash of each token, and a token expires after the period chosen when it was created, at most 365 days.
• Requests with a browser Origin header other than Ace's own get 403, so call the server from agents, IDEs and CLIs.
• Ace logs each tool call with the token, the tool, the incident read and the result, and keeps the log for 90 days. Settings > MCP shows when each token was last used.
• A tool result is capped at 200,000 characters. Longer incident context is cut off and ends with a link to the incident in Ace.

Revoke a tokenCopy Anchor Link

1. In Ace, open Settings > MCP.
2. Under Tokens, select Revoke next to the token.

The next request with that token gets 401. Revoked and expired tokens stay in the list with their status, so you can see which clients need a new one.

Limits and errorsCopy Anchor Link

Each request carries one JSON-RPC message, and batches aren't supported.

Tool errors, such as an unknown incident or a missing argument, come back as a normal tool result with isError: true and a message, such as No incident INS-0000-xxxx in this organization. An unknown tool returns JSON-RPC error -32602, and an unknown method returns -32601.

Next stepsCopy Anchor Link