Attio MCP: the complete guide for 2026
Attio's Model Context Protocol server is the part of Attio most worth understanding in 2026, and the part nobody writes about properly.
It is the reason an agent can be a teammate inside the CRM instead of a chat box pinned next to it. It is also the surface every other vendor is now scrambling to replicate. Most of the explainers online stop at "you can use Attio from Claude". That is not a guide, that is a teaser.
This is the full thing. What MCP is, the 37 tools it exposes, how to wire it to Claude, ChatGPT, Cursor, and Claude Code in under five minutes, what it cannot do (this is the part everyone skips), the prompts that actually return useful results, and when to reach for MCP versus Zapier, n8n, or the REST API.
What MCP is, in one paragraph
The Model Context Protocol is a small, open spec for letting AI agents talk to outside tools. Attio runs a hosted MCP server at https://mcp.attio.com/mcp. Any client that speaks MCP (Claude Desktop, Claude Code, ChatGPT custom connectors, Cursor, n8n, your own agent) can connect with OAuth, get a scoped token tied to the user that signed in, and call 37 tools that mirror most of what a human user can do in the Attio UI. No API key. No service to host. No webhook plumbing.
That is the whole thing. The rest of this post is what to do with it.
Setup in five minutes
Three clients cover 95% of real use. Pick the one you already use.
Claude.ai or Claude Code
Settings → Connectors → Add custom connector. Paste https://mcp.attio.com/mcp as the URL. Click Connect, sign in to your Attio workspace in the OAuth popup, approve the scopes. Done. Ask Claude "list the open deals" and it will call list-records against your Deals object and show you the result.
If you are on Claude Code, the same flow works through the IDE settings, or you can run claude mcp add --transport http attio https://mcp.attio.com/mcp in your terminal and Claude Code will walk you through the OAuth from there.
ChatGPT
Available on ChatGPT Plus, Business, Enterprise. Settings → Connectors → Add. Paste https://mcp.attio.com/mcp. Authorize. Custom GPTs can include the Attio connector as a tool, which is the version most teams build around.
Cursor
Cursor Settings → MCP → Add new MCP server. Same URL. Same OAuth.
Anything else
The endpoint is just an HTTP MCP server. If your agent framework supports MCP over HTTP, point it at https://mcp.attio.com/mcp. n8n, Activepieces, Composio, custom Python or TypeScript agents using the Anthropic SDK or the OpenAI SDK with MCP support all work the same way. The OAuth flow is standard. The tools list is identical.
The 37 tools, grouped by what they actually do
Attio's MCP server exposes 37 tools at the time of writing. The Attio team renamed several of them to follow MCP naming conventions in Q1 2026, but the old aliases still work. Grouped by use:
Records (6 tools)
list-records. Paginated read of an object's records with optional filters and sort. The workhorse.search-records. Keyword search across an object. Faster than filtering when you know the name.get-records-by-ids. Bulk fetch when the agent already has the IDs (good for follow-up calls).create-record. Write a new record. Fields and links inline.update-record. Partial update. Only the attributes you specify get touched.upsert-record. Match-on-attribute create-or-update. The right call for syncs from outside data.
What is missing from this group: there is no delete-record. Records can only be deleted from the Attio UI. That is a deliberate Attio choice and the right one. Agents cannot accidentally wipe your pipeline.
Lists (6 tools)
list-lists. Enumerate the lists in the workspace.list-records-in-list. Read the entries on a list with attached list-entry attributes.list-list-attribute-definitions. The schema of a list's per-entry attributes.add-record-to-list. Push a record onto a list.update-list-entry-by-id. Update a list entry when you have the entry ID.update-list-entry-by-record-id. Update when you only have the record ID. Saves a lookup.update-list. Change list-level settings.
Lists are where pipeline-stage logic lives in Attio. The MCP coverage here is what makes "move this deal to stage X" work as a one-line prompt.
Notes (4 tools)
search-notes-by-metadata. Filter notes by record, author, or date.semantic-search-notes. Vector search across note bodies. The right call for "find the call notes where the prospect mentioned pricing".get-note-body. Fetch the full body once you have the note ID.create-note. Write a new note attached to a record.update-note. Edit an existing note body.
semantic-search-notes is the most underrated tool in the list. It is the difference between "I have notes somewhere" and "the agent finds the relevant moment in 200ms".
Tasks (3 tools)
list-tasks. Read all tasks with filters.create-task. Create a task with assignee, due date, and linked records.update-task. Close, reassign, edit.
Comments (4 tools)
list-comments. Read comments on records.list-comment-replies. Read threaded replies.create-comment. Drop a comment on a record. The right call when an agent wants to ping a human.delete-comment. The only delete operation in the entire MCP surface. Comments are the one thing agents can remove.
Communications (8 tools)
search-meetings. Find meetings by attributes.get-call-recording. Fetch a recording's metadata and transcript.search-call-recordings-by-metadata. Filter calls.semantic-search-call-recordings. Vector search across transcripts. The headline tool for "find the moment the customer complained about onboarding".get-email-content. Fetch a synced email's body.search-emails-by-metadata. Filter emails by participants, dates.semantic-search-emails. Vector search emails.
This block is where most of the AI value lives. If your workspace has synced calls and emails, the semantic search tools turn the whole communication history into a queryable knowledge base. No additional setup. No separate vector store.
Reports (1 tool)
run-basic-report. Execute a saved Attio report and return rows. The bridge between agent prompts and the dashboards your team already uses.
Workspace (3 tools)
list-workspace-members. Read team members.list-workspace-teams. Read team structure.whoami. Return the calling user's identity. The right tool to call first in any session that needs scoped writes.
Attributes (1 tool)
list-attribute-definitions. Read the schema of any object. The agent's introspection. Without this, the agent does not know your custom fields exist.
That is the full surface.
The four things MCP cannot do
This is the section nobody else writes. Skip it and you will design an agent that hits a wall on day three.
1. Delete records
No delete-record exists. Records can only be deleted from the UI. Comments are the only object MCP can delete. If your agent's job involves cleaning up dead records, build a workflow that flags them for review and let a human run the bulk delete inside Attio.
2. Create attributes
No create-attribute-definition. You can read the schema (list-attribute-definitions) but you cannot change it. The agent works within whatever fields you have already built. If a prompt needs to write to a field, that field has to exist before the agent runs.
This is the constraint that quietly breaks half the agents people try to ship. The fix is upstream: design the schema for the agents first, then ship the agent. Not the other way around.
3. Create objects
No create-object. New custom objects are an Attio-UI-only operation. The agent operates inside the data model. It does not extend it.
4. Run automations or trigger workflows
MCP is read-write on records, lists, notes, tasks, comments, and communications. It does not start Attio workflows. If you want a workflow to fire, build the workflow inside Attio and have it triggered by a state change the agent caused (a stage move, an attribute write, a new record). The agent does the write, Attio's workflow engine does the trigger.
These four limits are not bugs. They are the line between "agent that uses the CRM" and "agent that rewrites the CRM". The first is safe and useful. The second is the kind of thing that takes down a production workspace at 3 AM.
Prompts that actually return useful results
The difference between "MCP demo" and "MCP in production" is the prompt structure. Five patterns we use every week.
Pattern 1: schema first, then act
Bad: "find John Smith and update his deal to stage Won."
Good: "Call list-attribute-definitions on Deals. Find the field that holds stage. Then search-records on People for John Smith. Then search-records on Deals filtered to the John Smith person. Move the stage to Won using update-record."
The schema-first prompt is slower by one tool call. It survives schema changes. The naive prompt breaks the first time you rename a field.
Pattern 2: semantic search for "find the moment"
Bad: "find the call where the customer mentioned pricing."
Good: "Use semantic-search-call-recordings with the query 'pricing objection contract value'. Return the top 3 recordings with timestamps and the relevant transcript excerpt."
Semantic search wants a description of the concept, not a literal quote. The more specific the concept, the cleaner the result.
Pattern 3: confirm before write
Bad: "update all stale deals to Lost."
Good: "Use list-records on Deals filtered to last activity older than 90 days and stage not Won or Lost. Return the list. Wait for me to confirm before calling update-record to set stage to Lost."
Claude Code defaults to this behavior on write operations, which is the right default. Other clients do not. The prompt has to enforce it.
Pattern 4: read across communications
Bad: "what does the customer think about onboarding?"
Good: "Use semantic-search-notes, semantic-search-call-recordings, and semantic-search-emails with the query 'onboarding friction first week'. Return the top result from each surface with a one-line summary and link back to the source."
The CRM has three places customer voice lives. MCP can read all three in parallel. Most prompts only ask one.
Pattern 5: write the comment, not the record
Bad: "this deal looks risky, mark it as such."
Good: "Use create-comment on the deal with the body 'Risk flagged: no activity for 21 days, last call mentioned budget freeze, churn keyword in latest email. Suggest CSM outreach this week.' Tag the deal owner."
A risk flag on a record is invisible. A comment is a notification to the owner that does not disturb the data model. For anything that needs human eyes, comments beat field writes.
When MCP beats Zapier, n8n, or the REST API
MCP is not the only way to drive Attio from outside. It is the right tool for some jobs and the wrong tool for others.
Reach for MCP when the work is conversational, needs reasoning, or needs to read across communications. Anything that involves "find me the moment when…" or "draft a follow-up that references…" is MCP work. The schema introspection and semantic search are the differentiators.
Reach for Attio workflows when the work is event-driven and rule-based. Record stage moves to Won → create task → post in Slack. No reasoning required. Attio's native workflow engine is faster, cheaper, and has no LLM round-trip.
Reach for Zapier, n8n, or Make when the work is multi-system and event-driven. Calendly booking lands → enrich via Clay → create lead in Attio → post in Slack. Zapier's chain of triggers is the right shape for these. MCP would force you to write the orchestration yourself.
Reach for the REST API directly when you need bulk operations, deterministic latency, or you are building a product feature with predictable load. The API gives you batch endpoints MCP does not expose, and you pay no LLM cost.
The bias most teams have wrong: they reach for MCP when a workflow would do, and reach for the API when MCP would be better. The litmus test is "is there reasoning in the loop". If yes, MCP. If no, workflow or API.
Performance and security, in real numbers
Latency. A read tool call (list-records, search-records) typically returns in 200-600 ms from the Attio MCP server. A semantic search call adds 300-800 ms for the embedding lookup. The LLM round-trip around it is usually the dominant cost; the MCP layer is not the bottleneck.
Rate limits. Per-user, generous for normal interactive use. Bulk operations that hit hundreds of records back-to-back can throttle. The fix is get-records-by-ids for batched reads, or dropping to the REST API for the truly bulky operations.
Auth model. OAuth scoped to the user that connected. The agent reads and writes with that user's permissions. If a user does not have access to a list, the agent connected as that user does not see it either. This is the right model and the one to insist on if you are building a multi-user product on top of MCP.
What an agent can see. Everything the connected user can see. Notes, calls, emails, attribute values, list memberships. Treat the agent as a teammate with full workspace permissions, because that is exactly what it is. Build a separate workspace member identity for any agent that runs unattended, with permissions scoped to the objects it needs.
The Craftt take
The MCP server is the single most important piece of Attio for anyone shipping AI on top of the CRM in 2026. Not the AI Attributes. Not the Research Agent. Those are useful, but they are inside the workspace. MCP is the part that makes the workspace addressable from outside, which is where most of the leverage is going to live.
Three implications for anyone deciding now:
- Design the schema for the agent first. Custom objects, attributes, list structure, all of it. MCP cannot create them. The agent works in whatever shape you give it. The shape compounds.
- Treat the agent as a workspace member. Give it a real seat, a name, and scoped permissions. Run it under that identity. Audit log shows who did what. Future-you will thank present-you.
- Reach for MCP when reasoning is in the loop. Otherwise use workflows or the API. The bias to over-use MCP is the most common mistake we see. Each tool has a job. Use the right one.
The CRM is no longer the destination. It is the spine the agents read and write to. MCP is the surface that makes that real today.
Sources
Free audit of your Attio workspace
If you want a second pair of eyes on whether your workspace is ready for agents, or you want the MCP-driven workflows shipped for you, we run a free 48-hour audit. You add us as an Attio expert, no extra seat and no billing. We send back a one-page written teardown ranked by impact, the three highest-leverage MCP workflows to ship first, and a 5-minute Loom walking through the top one. No call, no pitch. 5 slots a week.
Need help with your Attio setup?
We migrate teams, build data models, wire automations, and train Claude agents inside your workspace. Discovery call is free.
Book a free discovery callReady when you are.
Two ways in. Pick the friction that fits.