Jun 23, 2026

Attio MCP vs Attio API for Agentic Tool Calling

TL;DR

Attio's hosted MCP server (GA February 2026) ships 37 tools across records, lists, comments, notes, tasks, meetings, emails, workspace, and reporting. Webhooks, schema writes (creating objects and attributes), and headless auth are absent from the MCP surface.
MCP auth is OAuth only and interactive. The REST API supports two bearer-token types: a workspace API key (non-interactive, good for single-workspace and background jobs) and per-user OAuth 2.0 (for multi-tenant products). Your credential model changes with the path.
Attio tokens do not follow the short-lived-plus-refresh pattern. Workspace API keys do not expire, and the OAuth flow returns a long-lived access token with no documented refresh-token rotation. The production problem is storage, isolation, scope, and revocation detection, not refresh cycles.
For multi-tenant B2B agents, both paths produce one credential per user. Neither path stores, isolates, scopes, or detects revocation for you. That is infrastructure regardless of which path you choose.
Scalekit's Attio connector handles the OAuth flow, per-user token storage in a token vault, scope enforcement, and audit logging for the API path, so the MCP vs API decision does not change your auth infrastructure.

Your agent needs to read and write Attio. Attio ships a hosted MCP server at mcp.attio.com/mcp and a full REST API at api.attio.com/v2. They are not the same thing: different capability coverage, different auth paths, different operational surface area in production. The choice also is not permanent; what your agent does determines which path fits. Here is how to pick.

What Attio MCP and Attio API actually are

Attio MCP

Attio MCP is Attio's hosted, Attio-maintained MCP server, reachable at https://mcp.attio.com/mcp. It reached general availability in February 2026 and is built for LLM consumption, with human-readable responses and MCP safety annotations.

Authentication is OAuth only. You log in with your Attio account, no API keys; the agent is authenticated as your Attio user, and access is bounded by that user's workspace permissions. Read operations are auto-approved, while write operations request user confirmation. Official reference: Attio MCP overview.

Attio API

The Attio REST API exchanges JSON over HTTPS at https://api.attio.com/v2. It exposes the full workspace surface: objects, attributes, records, lists, entries, notes, tasks, comments, threads, meetings, call recordings, transcripts, files, workspace members, and webhooks.

Authentication accepts any bearer token in the Authorization header. Two token types matter: a workspace API key generated under Workspace Settings, and a per-user OAuth 2.0 access token from the Authorization Code flow. Official reference: Attio REST API overview.

Comparing them where it matters for agents

What your agent can actually do

The hosted MCP covers the conversational CRM surface well: search, record CRUD, lists, notes, tasks, comments, and AI-native semantic search over notes, emails, and calls. The gaps appear when an agent needs to react to changes or manage the workspace schema.

Capability

Attio MCP (hosted)

Attio REST API

Search records (fuzzy / full-text)

Yes

Read and create records (people, companies, deals)

Yes

Update and upsert records

Yes

Manage lists and list entries

Yes

Notes, tasks, comments

Yes

Semantic search (notes, emails, calls)

Yes

Partial: build it yourself over search endpoints

Read attribute and object schema

Yes: read only

Yes

Create or modify objects and attributes

Yes

Webhooks and real-time change events

Yes

Files and transcript endpoints

Partial: call recordings only

Yes

Headless, non-interactive auth

Yes: workspace API key

Granular per-app OAuth scope selection

No: inherits user permissions

Yes

What the official tool lists tell you

This series sources capability claims from the published tool list, not assumptions. The official Attio MCP overview documents exactly 37 tools across nine categories, so the gaps below are structural, not pending features.

Three gaps are worth naming precisely. First, there is no webhook tool; the MCP cannot subscribe to record, list, note, task, or comment events, while the REST API exposes signed, filterable webhooks (see the Attio webhooks guide). Second, the MCP can read schema with list-attribute-definitions but cannot create objects or attributes; that lives only in the API. Third, the MCP is OAuth-interactive by design, so a background agent with no user present cannot complete the flow.

What the MCP makes easier is also real. Semantic search over notes, emails, and call recordings ships as first-class tools, write confirmations are built in, and the end user manages no tokens. Replicating those affordances over raw REST is your work, not Attio's.

The auth path each one puts you on

The hosted MCP requires OAuth and a browser-based consent step. There is no API-key option on this path. Every user who connects authorizes as themselves, and the resulting session inherits that user's exact Attio permissions.

The REST API gives you a choice. A workspace API key is a non-interactive bearer token, scoped to one workspace, that does not expire and is revoked by deletion. Per-user OAuth 2.0 issues a token per authorizing user through the Authorization Code flow, which is the right model for a product where each customer connects their own workspace.

The token-lifecycle nuance specific to Attio

Attio does not match the short-lived-access-token-plus-refresh model you carry for Slack or Google. Workspace API keys do not expire. The OAuth token endpoint returns a long-lived access token with no documented refresh-token rotation. The practical consequence: long-lived credentials raise the stakes on storage and revocation. A user can disconnect your app or an admin can delete a key at any time, and your agent only learns this from a 401. Detection and re-authorization, not refresh timers, are the failure mode to engineer for.

The multi-tenant reality

For a B2B agent serving 40 reps across 8 workspaces, the per-user OAuth path means 40 tokens to store encrypted, isolate per tenant, scope correctly, and revoke on offboarding. The MCP path produces the same per-user token, just minted through its own consent flow. Neither path solves storage, isolation, scope, or revocation detection for you. This is the credential ownership problem that exists regardless of which integration surface you choose.

What you own in production

On the MCP path

Attio manages hosting, tool schemas, and response formatting. You still own per-user token storage, tenant isolation, and revocation handling. You also accept the MCP's per-workspace tiered rate limits: 100 reads per second, 25 writes per second, 300 searches per minute, and 2 semantic searches per second, shared per tier per workspace.

On the REST API path

You own the full stack: endpoint selection, request construction, the typed-array attribute model, per-attribute filter syntax, pagination, error handling, and the token lifecycle. The API applies 100 reads per second and 25 writes per second, plus score-based limits on list records and list entries queries summed across all apps and access tokens. More surface area, more control.

Schema stability and drift

MCP tool schemas are managed by Attio and can change when Attio updates the server; your agent picks up changes without a redeploy, but you do not control the cadence. The REST API is a stable, documented contract you call directly. For deterministic pipelines where an unexpected schema change is an incident, the direct API is the more predictable dependency.

When to use MCP, when to use the API

Use Attio MCP when:

Your agent is interactive and user-present: a CRM assistant in Claude, ChatGPT, or Cursor where OAuth consent is natural.
The job is search, retrieval, and record or note creation in natural language, including semantic search over notes, emails, and calls.
You want write confirmations and Attio-maintained tool schemas without writing API integration code.
The agent is single-user or single-workspace rather than a multi-tenant B2B product.

Use the Attio REST API when:

The agent runs headless: scheduled syncs, background enrichment, or pipeline jobs with no user present, where a workspace API key fits.
The agent must react to changes via webhooks, or manage the workspace schema by creating objects and attributes.
You are multi-tenant and need per-user OAuth with explicit scope control and tenant isolation.
You need deterministic control over filters, pagination, and versioned behavior for a production pipeline.

The credential problem that exists on both paths

What neither path gives you

Both paths give you a token per user. Neither gives you a vault, tenant isolation, scope enforcement at call time, or revocation detection. That infrastructure is built separately, regardless of which path you chose.

In a multi-tenant Attio agent, every user has their own credential. Fifty customers means fifty credentials to store encrypted, isolate per tenant, and invalidate when a user disconnects your app or an admin deletes a key. Because Attio tokens are long-lived, a credential that leaks or outlives an employee stays valid until something explicitly removes it.

The shared-key failure mode

A single workspace API key looks correct in a demo. In production, every record update logs as a service account, list-level permissions collapse to whatever the key holds, and per-user pipeline visibility breaks. The audit trail shows one identity for actions taken on behalf of many people.

Where Scalekit fits

Scalekit's Attio connector resolves the per-user credential on every tool call, so each action runs as the user who authorized it. Tokens live in Scalekit's token vault, encrypted at rest and isolated per tenant, never in agent runtime or model context. The same auth infrastructure works whether you build against MCP or the REST API; the path decision does not change what you need at the credential layer.

Connecting Attio through Scalekit

Why this matters for an Attio agent

Attio requires you to register your own OAuth app; there is no shared managed app to borrow. You own the ^{Client ID}, ^{Client Secret}, the redirect URI, the typed-array data model, and Attio's fine-grained scopes. Scalekit's connector wraps Attio's REST API behind one interface, exposes around 50 prebuilt tools (a superset of the hosted MCP's 37, including webhook and attribute or object management), and resolves per-user identity on every call. Connector reference: Attio connector docs.

One-time setup

Register your Attio OAuth app at build.attio.com, then create the Attio connection in the Scalekit dashboard under AgentKit > Connections, paste your ^{Client ID} and ^{Client Secret}, and select the minimum scopes (for example ^{record_permission:read-write}, ^{note:read-write}, ^{task:read-write}, ^{webhook:read-write}). Note the exact connection name; the value you pass in code must match the connection name configured in the Scalekit dashboard exactly. This is the single most common integration error.

Install the SDK

# Node.js npm install @scalekit-sdk/node # Python pip install scalekit-sdk-python

Authorize a user and make a first call (Python)

The agent application manages only the Scalekit API key; no Attio secrets or user tokens touch your code.

import os import scalekit.client from dotenv import load_dotenv load_dotenv() scalekit_client = scalekit.client.ScalekitClient( client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), env_url=os.getenv("SCALEKIT_ENV_URL"), ) actions = scalekit_client.actions # connection_name must match the Attio connection name in your Scalekit dashboard connection_name = "attio" identifier = "user_123" # Resolve or create the per-user connected account account = actions.get_or_create_connected_account( connection_name=connection_name, identifier=identifier, ) if account.connected_account.status != "ACTIVE": link = actions.get_authorization_link(connection_name=connection_name, identifier=identifier) print("Authorize Attio:", link.link) input("Press Enter after authorizing...") # First call: verify the token and workspace result = actions.execute_tool( tool_name="attio_get_current_token_info", identifier=identifier, tool_input={}, ) print(result)

Authorize a user and make a first call (Node.js)

import { ScalekitClient } from '@scalekit-sdk/node'; import 'dotenv/config'; const scalekit = new ScalekitClient( process.env.SCALEKIT_ENV_URL!, process.env.SCALEKIT_CLIENT_ID!, process.env.SCALEKIT_CLIENT_SECRET!, ); const actions = scalekit.actions; // connectionName must match the Attio connection name in your Scalekit dashboard const connector = 'attio'; const identifier = 'user_123'; const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }); console.log('Authorize Attio:', link); process.stdout.write('Press Enter after authorizing...'); await new Promise((r) => process.stdin.once('data', r)); const result = await actions.executeTool({ connector, identifier, toolName: 'attio_get_current_token_info', toolInput: {}, }); console.log(result);

Running a Claude agent over scoped Attio tools (Python)

The agent receives only the tools the current user's connected account is authorized to call, not the full catalog. That keeps tool selection accurate and the token surface small.

import anthropic from google.protobuf.json_format import MessageToDict client = anthropic.Anthropic() # Retrieve the tools authorized for this user's connected account scoped_response, _ = actions.tools.list_scoped_tools( identifier="user_123", filter={"connection_names": ["attio"]}, page_size=100, # fetch beyond the default page so no connector tools are missed ) llm_tools = [ { "name": MessageToDict(t.tool).get("definition", {}).get("name"), "description": MessageToDict(t.tool).get("definition", {}).get("description", ""), "input_schema": MessageToDict(t.tool).get("definition", {}).get("input_schema", {}), } for t in scoped_response.tools ] messages = [{"role": "user", "content": "Find the Acme deal and add a task to follow up Friday"}] while True: response = client.messages.create( model="claude-sonnet-4-6", max_tokens=1024, tools=llm_tools, messages=messages, ) if response.stop_reason == "end_turn": print(response.content[0].text) break tool_results = [] for block in response.content: if block.type == "tool_use": result = actions.execute_tool( tool_name=block.name, identifier="user_123", tool_input=block.input, ) tool_results.append({ "type": "tool_result", "tool_use_id": block.id, "content": str(result.data), }) messages.append({"role": "assistant", "content": response.content}) messages.append({"role": "user", "content": tool_results})

Running a LangChain agent over scoped Attio tools (Python)

Scalekit returns native LangChain tool objects, so the agent code needs no Scalekit-specific reshaping.

from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage, ToolMessage tools = actions.langchain.get_tools( identifier="user_123", connection_names=["attio"], page_size=100, # avoid missing tools when a connector has more than the default page ) tool_map = {t.name: t for t in tools} llm = ChatOpenAI(model="gpt-4o").bind_tools(tools) messages = [HumanMessage("List open deals over 50k and summarize the top three")] while True: response = llm.invoke(messages) messages.append(response) if not response.tool_calls: print(response.content) break for tc in response.tool_calls: result = tool_map[tc["name"]].invoke(tc["args"]) messages.append(ToolMessage(content=str(result), tool_call_id=tc["id"]))

Prefer the MCP transport instead

If you would rather drive Attio through MCP, point a Scalekit-generated, per-user MCP URL at any MCP host. The endpoint is static; the identity behind it is per-user.

{ "mcpServers": { "scalekit": { "transport": "streamable-http", "url": "your-scalekit-mcp-url" } } }

Why this pays off downstream

The same ^execute_tool interface works across every connector, so adding Salesforce, HubSpot, Gmail, or Slack later inherits the same vault, scope checks, and delegation pattern with zero new auth code per connector. For multi-tool agents, that removes N separate OAuth implementations from your application layer.

For multi-tenant agents, observability is the larger payoff. Every delegation logs who authorized it, which agent and tool ran, the scope in effect, and the result, and the trail is exportable to your SIEM. When a security reviewer asks under whose credentials the agent updated a record, you have an answer per action rather than a shared service-account entry. Pagination, rate limits, retries, and scope checks are handled before the response reaches your agent.

Need a tool or capability that is not covered yet

If your Attio workflow needs a tool the connector does not expose yet, request it in the Scalekit Slack community or talk to the team. New connector tools typically ship within a week.

Which one to build against

If your agent is interactive and user-present, and its job is searching, reading, and authoring Attio content, the hosted MCP is the faster route to a working agent. The semantic-search tools and write confirmations are built in, and Attio maintains the schemas.

If your agent runs headless, must react to changes via webhooks, manages the workspace schema, or serves many tenants with per-user scope control, build against the REST API directly. The MCP's OAuth-only, retrieval-focused surface is a genuine constraint, not a configuration option. Most production B2B agents end up using both: MCP for interactive features, the API for background work. Either way, the credential problem is the same, and long-lived Attio tokens make production-grade storage, isolation, and revocation detection the part that actually needs solving.

Browse the Scalekit Attio connector: scalekit.com/agent-connector/attio

No items found.

On this page

Introduction
‍

This is some text inside of a div block.