Reference — lookup information.
What is Affinity MCP?
Affinity MCP (Model Context Protocol) is the server interface that lets external AI tools query and update your Affinity CRM. It’s a standards-based way for AI clients to call structured tools —search_companies_top_matches, create_note, search_opportunities — against live Affinity data, with your user’s permissions enforced on every call.
For setup steps, follow the per-client guides at developer.affinity.co/pages/mcp/supported-clients.
Who should use Affinity MCP
- Associates & analysts doing deal research, IC prep, founder meeting prep
- Partners running portfolio check-ins and LP communication prep
- Operators keeping the CRM clean: updating fields, creating notes, setting reminders from chat
- Developers building agentic workflows over Affinity data
When to use MCP vs Affinity AI Chat
See Affinity AI Chat Overview for the in-app option.
Use cases by role
Associates and analysts — deal research and IC prep
- “Find seed and Series A SaaS companies in healthcare we’ve never contacted.”
- “Summarize all notes on Acme Corp from the last 90 days.”
- “Show me upcoming meetings with founders this week.”
- “Who on our team has the strongest relationship with the partners at Benchmark?”
- “Create a note on Acme Corp: [paste meeting summary]“
Partners — portfolio and LP context
- “List portfolio companies I haven’t checked in with this quarter.”
- “Summarize last three interactions with [LP firm name].”
- “Show me deals where the next milestone is overdue.”
Operators — CRM hygiene
- “Show me opportunities with no Stage field set in the last 30 days.”
- “Update the Stage field on the Acme deal to ‘Due Diligence’.”
- “Set a reminder to follow up with Jane Smith in two weeks.”
Developers — automation
- Use MCP from a custom-built agent (e.g., LangChain, your own orchestrator) to enrich, sync, or summarize.
- See Available tools for the full schema.
Hosted vs Local
For most users: pick Hosted. For Local setup, see Local Setup at developer.affinity.co.
What data MCP can access
MCP tool calls execute as the authenticating user. You can read, update, delete, or merge anything you’d be able to directly in Affinity — and nothing else.- List access: only lists you’ve been granted access to
- Field visibility: respects field-level permissions
- Role gates: enterprise role restrictions still apply
- Read-only option: restrict a connection to read-only — either uncheck the write scope at OAuth consent, or block the write, delete, and merge tools in your AI client’s tool permissions (for example, in Claude). To keep writes but prevent deletion, switch off only the delete tools
Capabilities and limitations
What MCP can do
MCP exposes 50+ tools across your CRM — it can both read and write.- Query companies, people, opportunities, lists, saved views, fields, notes, meetings, transcripts, reminders, and relationship strength
- Search by natural language (company semantic search), keyword, list membership, recency, owner, status, and more; filter list entries with nested AND/OR conditions and location filters, and sort by up to five fields
- Create companies, people, opportunities, lists, list entries, fields, and dropdown options
- Create notes (on a person, company, opportunity, or meeting) and reminders; edit or delete notes you created
- Log interactions — meetings, calls, or messages
- Upload and download files on any record — so an AI client can read a deck you already have, or write an artifact it generated back onto the company
- Update field values, opportunities, people, and companies; view field-value change history
- Delete list entries, opportunities, companies, and people, and merge duplicate people and companies. Every delete and merge shows you what it will affect and waits for your explicit confirmation.
- Return data filtered by your user’s CRM permissions
Current limitations
- MCP cannot bulk-update entries across many lists in one call (work entry-by-entry, or use the API)
- There’s no dedicated bulk file upload, though a client can work through several files one after another. Files are capped at 100 MB — see Supported file types for upload
- Some tools depend on features being enabled for your org: note and file search require Deal Assist, and meeting tools require unified events onboarding
- Deletes can’t be undone; data-recovery options are the same as for deletes made in Affinity. Global (Affinity-enriched) companies can’t be deleted, and deleting an entry on an opportunity list deletes the opportunity itself
- You can edit or delete only notes you created, and a note with @mentions can’t be edited. Deleting a note also deletes its replies and attached files
- Merging people requires an org admin with the Manage Duplicates permission. An admin can undo a merge of local records in Settings → Duplicate Management → Merged; a merge involving a global company can’t be undone
- If you connected before September 24, 2026, restart your AI client or start a new session to load these tools.
- Some clients connect with an API key instead of OAuth (see Authentication)
Authentication
Two methods:- OAuth: One-click browser auth via
login.affinity.co; no key to manage. Supported by Claude (all surfaces), ChatGPT (Free plan and up), and Notion (Custom Agents). At consent you can grant read-only by unchecking the write scope. Enable or disable each OAuth client for your org under Affinity → Settings → Affinity MCP; turning a client off disconnects everyone who connected it through OAuth. To revoke just your own connection, disconnect Affinity in your AI client’s settings. On Enterprise, the Manage MCP Agents permission (Users & Permissions → Roles) controls which roles can change these settings; it doesn’t limit who can use MCP. - API key: A long-lived key passed as a
Bearertoken in theAuthorizationheader. Used by Copilot, Gemini CLI, and other clients (Notion also supports it). Create a key with + New App, or revoke one, under Affinity → Settings → Manage Apps. You can have more than one active key, so use a separate key for each client; you can then revoke one without breaking the others.
Security and privacy
- The MCP server is stateless. No CRM data, prompts, or AI responses are persisted.
- Affinity sees only the structured tool calls your AI client makes — not your typed prompts. Your prompts are governed by your AI provider’s policy.
- All tool calls run with your user’s CRM permissions.
- OAuth tokens are user-scoped and revocable; API keys can be rotated.