> ## Documentation Index
> Fetch the complete documentation index at: https://support.affinity.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Affinity MCP Reference

> Reference: Affinity MCP Reference

<Note>
  **Reference** — lookup information.
</Note>

## 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`, `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](https://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

| You want to...                                                       | Use                                   |
| -------------------------------------------------------------------- | ------------------------------------- |
| Chat with Affinity data inside the Affinity web app                  | **Affinity AI Chat** (Beta, no setup) |
| Query Affinity from Claude / ChatGPT / Copilot / Notion / Gemini CLI | **MCP**                               |
| Build a custom agent that orchestrates Affinity + other tools        | **MCP**                               |
| Get answers without leaving your preferred AI surface                | **MCP**                               |

See [Affinity AI Chat Overview](/s/article/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](https://developer.affinity.co/pages/mcp/available-tools) for the full schema.

## Hosted vs Local

|                | Hosted                         | Local                                                                       |
| -------------- | ------------------------------ | --------------------------------------------------------------------------- |
| Who runs it    | Affinity                       | You                                                                         |
| Updates        | Continuous, automatic          | You re-install to upgrade                                                   |
| Best for       | 95% of users                   | Teams with strict security / customization needs                            |
| Server URL     | `https://mcp.affinity.co/mcp`  | `http://localhost:<port>/mcp`                                               |
| Transport      | Streamable HTTP                | STDIO                                                                       |
| Install        | None                           | `uvx affinity-mcp` (installed and run via [uv](https://docs.astral.sh/uv/)) |
| Authentication | OAuth or API key               | API key only                                                                |
| Cost           | Included in your Affinity plan | Same                                                                        |

For most users: pick Hosted. For Local setup, see [Local Setup at developer.affinity.co](https://developer.affinity.co/pages/mcp/local-setup).

## What data MCP can access

MCP tool calls execute as the authenticating user. You can read and update anything you'd be able to read or update 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 tools in your AI client's tool permissions (for example, in Claude)

## 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
* Create companies, people, opportunities, lists, list entries, fields, and dropdown options
* Create notes (on a person, company, opportunity, or meeting) and reminders
* Log interactions — meetings, calls, or messages
* Update field values, opportunities, people, and companies; view field-value change history
* 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)
* MCP can't see file attachments, only their metadata
* Some tools depend on features being enabled for your org: note and file search require **Deal Assist**, and meeting tools require **unified events** onboarding
* 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 MCP per client, and revoke connections, under **Affinity → Settings → Affinity MCP** (Enterprise admins can also gate by role under **Users & Permissions → Roles → Manage MCP Agents**).
* **API key**: A long-lived key passed as a `Bearer` token in the `Authorization` header. Used by **Copilot**, **Gemini CLI**, and other clients (Notion also supports it). Create, rotate, or revoke keys under **Affinity → Settings → Manage Apps**.

See [Authentication at developer.affinity.co](https://developer.affinity.co/pages/mcp/authentication) for full details.

## 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.

See [Affinity MCP: Security & data handling](/s/article/Affinity-MCP-security) for the full picture, or [developer.affinity.co/pages/mcp/security](https://developer.affinity.co/pages/mcp/security).