Reference

MCP server

Recalled ships an official Model Context Protocol server so AI agents (Claude Desktop, Cursor, ChatGPT, custom agents built on the official MCP SDKs) can read and act on your audit trail directly.

> Plan requirement. The MCP endpoint is available on Starter, Pro and Scale. Free accounts can still mint API keys for the SDK and REST API, but /v1/mcp returns a JSON-RPC error pointing at the upgrade page. Upgrade at recalled.dev/dashboard/billing.

The MCP endpoint reuses the API keys you already have. Same authentication, same scoping by project, no new infrastructure to set up. If you can call /v1/events, you can use the MCP, provided the project owner is on a paid plan.

Endpoint

text

POST https://api.recalled.dev/v1/mcp

The endpoint speaks Streamable HTTP transport (MCP spec 2025-03-26). It runs in stateless mode: every JSON-RPC request gets a fresh server, isolated to the API key it was authenticated with. There is no session token to manage on your side.

Authentication

Same Bearer token as the REST API:

text

Authorization: Bearer rec_live_<prefix>_<secret>
Content-Type: application/json

The MCP scopes everything to the project that owns the API key. An MCP session bound to project A can never read project B's events.

Connect from Claude Desktop

Edit claude_desktop_config.json and add:

json

{
  "mcpServers": {
    "recalled": {
      "url": "https://api.recalled.dev/v1/mcp",
      "headers": {
        "Authorization": "Bearer rec_live_xxx_yyy"
      }
    }
  }
}

Restart Claude Desktop. You should see Recalled appear in the tools list.

Connect from Cursor

Open Cursor Settings, MCP, then add a new server:

json

{
  "name": "recalled",
  "transport": "http",
  "url": "https://api.recalled.dev/v1/mcp",
  "headers": {
    "Authorization": "Bearer rec_live_xxx_yyy"
  }
}

Tools available

Tool	What it does
`get_project_info`	Identification of the project this session is bound to and the current API key's scopes.
`get_recent_events`	Most recent events newest first, capped at 100.
`search_events`	Free text search across action, actor name, actor email, actor id. Cursor pagination.
`list_events`	Structured filters (action, actor, organization, IP, date range). Cursor pagination.
`retrieve_event`	Fetch a single event by id with full details.
`get_event_receipt`	Return a portable, citable receipt for one event with public verification_url and view_url.
`list_actions_summary`	Top actions over a window of N days, with count and percent share.
`verify_chain`	Recompute every hash and HMAC signature, return integrity report.
`usage_summary`	Current month event count vs plan limit, percent used.
`delete_actor`	GDPR Article 17 erasure. Requires `confirm: true` to actually run.
`audit_actor_plan`	Returns a step by step audit plan for a specific actor. The assistant then executes it by calling the data tools.
`investigate_incident_plan`	Returns a step by step investigation plan for events around a given timestamp.
`compliance_check`	Returns a GDPR / SOC 2 / ISO 27001 readiness audit plan that the assistant runs by chaining the data tools.
`get_setup_guide`	Returns the opinionated setup prompt for adding Recalled to a codebase. EN or FR.

Resources available

The same data exposed by get_project_info, usage_summary and get_recent_events is also published as MCP resources, for clients that prefer the resource model over tool calls. Tools and resources stay in sync; pick whichever your client supports best.

URI	What it exposes
`recalled://project/info`	Project metadata and the API key's id, name, prefix and scopes.
`recalled://usage/current`	Current month usage, plan limit, percent used.
`recalled://events/recent`	The 50 most recent events for situational awareness.

Prompts available

Prompts are reusable recipes that combine tools and resources to answer common questions. They surface as quick actions in clients that support MCP prompts (Cursor, ChatGPT, custom agents). Claude Desktop currently ignores prompts and only sees tools, so each prompt is also exposed as a *_plan tool with the same content.

Prompt	Tool equivalent	What it produces
`/audit_actor`	`audit_actor_plan`	Audit one actor's activity over a chosen window. Inputs: `actor_id`, optional `days`.
`/investigate_incident`	`investigate_incident_plan`	Investigate events around a timestamp, propose a root cause narrative. Inputs: `at` (ISO), optional `window_minutes`, optional `focus`.
`/compliance_check`	`compliance_check`	GDPR / SOC 2 / ISO 27001 readiness assessment based on the data in the project.

Example session

Once connected, you can ask the assistant questions in plain language and it will pick the right tools.

text

You: who deleted invoices in the last 7 days?
Assistant: (calls list_events with action="invoice.deleted", date_from set to 7 days ago)
Assistant: 4 invoices were deleted by 2 distinct actors over the last 7 days. Most recent was 3 hours ago by user_42.

text

You: run a compliance check on this project.
Assistant: (calls /compliance_check, then verify_chain, list_actions_summary, reads project_info)
Assistant: GDPR green, SOC 2 amber (admin role changes not consistently logged), ISO 27001 amber. ...

Pricing

The MCP is available on every plan, including Free. It does not consume your event quota: it reads existing events and exposes the same actions as the REST API. The actions a tool performs (e.g. ingestion via REST, GDPR erasure) are still billed and rate limited like any other call.

Security model

Bearer token only, in the Authorization header. Never in query strings.
HTTPS only.
No "token passthrough": the MCP server validates the key against your project before doing anything.
Each request opens its own scoped server and closes it on response. No shared state between tenants.
Destructive tools (delete_actor) require an explicit confirm argument so an agent cannot run them by accident.

Troubleshooting

"Invalid API key": the key was not found, was revoked, or the prefix does not match. Generate a new one in the dashboard.

"Method Not Allowed" on a GET request: the endpoint is POST only in stateless mode. MCP clients should send JSON-RPC over POST.

Rate limited: the MCP shares the global rate limit of /v1/*. If your agent loops aggressively, batch its calls or back off.