Skip to main content

​
Immediate Value

After this tutorial, your AI tool of choice — Claude (Desktop, Web, or Claude Code), ChatGPT, Microsoft Copilot, Notion, Gemini CLI, or another MCP-compatible client — will be able to query your Affinity data directly. You’ll be able to ask questions like “What deals are in stage X?”, “Summarize my last interactions with this person”, or “Who at our firm has the warmest relationship with Company Y?” without leaving the AI tool.

​
Prerequisites

  • You’ve completed at least the basics of Tier 1 (Lists, Profiles, Search).
  • Your workspace is on a Scale, Advanced, or Enterprise plan. Check Settings → Billing if you’re unsure.
  • You have an AI tool that supports the Model Context Protocol (MCP): Claude (Desktop, Web, or Claude Code), ChatGPT, Microsoft Copilot, Notion (Custom Agents), Gemini CLI, or any other MCP-compatible client.

​
Quick-Start Roadmap

  1. Understand what Affinity MCP is (in plain language)
  2. Check your plan and whether your client is switched on
  3. (Admin) Control which clients can connect to MCP
  4. Generate an Affinity API key (for clients that need one)
  5. Connect your AI client — Claude, ChatGPT, Copilot, Notion, Gemini, or others
  6. Run your first query
  7. Try the capability areas
  8. Run a prepackaged skill
  9. Audit and revoke unused access
  10. Go deeper with the dev docs

​
Why MCP Matters

Most of your work happens in your AI tool now — chat windows, research, drafting. The friction is that the AI doesn’t know your CRM data, so you spend time copy-pasting context back and forth. MCP closes that loop: your AI tool can read directly from Affinity, answer questions against live CRM data, and surface relationship intelligence in the conversation you’re already having. This isn’t “AI inside Affinity” — it’s the other direction. You use whichever AI tool you prefer, and Affinity becomes one of the data sources it can reach.
See Affinity AI chat overview for context on how MCP fits alongside Affinity’s other AI features.

​
Task 1: Understand What Affinity MCP Is

​
Context

MCP stands for Model Context Protocol — a standard way for AI assistants to securely connect to data sources like CRMs, calendars, and document stores. Affinity exposes an MCP server, which means any MCP-compatible AI client can query your Affinity data using your permissions. What this isn’t: it’s not a chatbot bolted onto Affinity. It’s a connection your existing AI tool can make. What it enables:
  • Ask pipeline questions in Claude Desktop and get current numbers
  • Summarize a profile’s interaction history in your AI flow
  • Find warm intro paths to a company without leaving your AI tool
  • Create companies, people, and opportunities; update fields; add, edit, and delete notes; set reminders; log a call; delete or merge records you no longer need — all conversationally
  • Read a pitch deck already on a record, or save a file your AI generated back onto the company

​
Expected Outcome

You understand the model: Affinity is the data source, your AI tool is the interface.

​
📚 Help Center

​
Task 2: Check Your Plan and Whether Your Client Is On

​
Context

Two things decide whether you can connect: your Affinity plan, and whether your admin has left your AI client switched on. There’s nothing to enable for yourself — you connect from inside your AI tool.

​
Action

  1. Check your plan: go to Settings → Billing. MCP is available on Scale, Advanced, and Enterprise plans. If you’re on a different plan, contact your account manager.
  2. Check your client is allowed: MCP is on by default for Claude, ChatGPT, and Notion. An admin can switch any OAuth client off for the whole organization. If your connection is refused, ask your admin (see Task 3).
  3. Check your AI tool’s own requirements: some clients need their own workspace admin to allow custom connectors first — for example, Claude Team or Enterprise, and Notion Business or Enterprise.
Where setup happens. You connect inside your AI client (Task 5). Settings → Affinity MCP in Affinity is the admin page for controlling which clients the organization allows — it isn’t where you connect.

​
Expected Outcome

You know whether you can connect straight away, or need your admin first.

​
Task 3: (Admin) Control Which Clients and Roles Can Use MCP

Admin only. Skip this task if you’re not configuring access for others. End-users go to Task 4.

​
Context

MCP is on by default for Claude, ChatGPT, and Notion. Admins decide which clients stay available to the organization.

​
Action

  1. Go to Settings → Affinity MCP and turn each OAuth client on or off for your organization. Turning a client off disconnects everyone in your organization who connected it through OAuth. The setting only affects OAuth connections; users can still connect a client manually with an API key.
  2. Enterprise only: to choose which roles can change these settings, go to Settings → Users & Permissions → Roles and set the Manage MCP Agents permission (Enterprise Admins and Admins have it by default). This permission doesn’t limit who can use MCP.
  3. If you want a connection to be read-only, tell users to uncheck the write scope when they authorize an OAuth client. That blocks every create, update, and delete call for that connection. Some clients, such as Claude, also let you switch off individual write, delete, and merge tools — for example, switch off only the delete tools to allow edits but not deletion.
MCP access grants the AI tool the same data visibility as the user. If a user can see restricted lists or sensitive opportunities in Affinity, their AI agent can too. Grant carefully — especially for senior users with broad access.

​
Expected Outcome

Only the clients — and, on Enterprise, the roles — you intend can connect to Affinity.

​
📚 Help Center

​
Task 4: Generate Your Affinity API Key

​
Context

Some AI clients (Copilot, Gemini, Notion Bearer mode, and most “other” MCP clients) authenticate to Affinity using an API key. OAuth-only clients (Claude, ChatGPT, Notion OAuth) handle auth automatically inside their own app — if you’re using one of those, skip ahead to Task 5.

​
Action

  1. Go to Settings → Manage Apps.
  2. Click + New App (if a menu opens, choose API Key).
  3. Give it a name and description you’ll recognize when auditing later — for example, MCP: Gemini CLI and Copilot.
  4. Copy the key immediately — Affinity shows it once and cannot retrieve it again.
  5. Store it in your password manager or your team’s secrets vault.
Use a separate API key for each client. You can have more than one active key, and creating a new one doesn’t revoke the others. With one key per client, you can revoke a single client’s access without breaking the rest.
Treat the API key like a password. Anyone holding it can query your Affinity data with your permissions. Don’t paste it in chat threads, public docs, or unencrypted files.

​
Expected Outcome

You have an Affinity API key ready to paste into your AI client’s MCP configuration.

​
📚 Help Center

​
Task 5: Connect Your AI Client

​
Context

Different AI clients have slightly different setup flows. Pick yours below.
Auth: OAuth (no API key needed).Claude Desktop or Web: Affinity is now in Claude’s connector directory — no manual URL needed.
  1. In Claude, open Settings → Connectors.
  2. Search for “Affinity” and click “Add” (on Team or Enterprise, a workspace Owner clicks “Add to your team” first).
  3. Click “Connect” and complete the OAuth flow in your browser.
Claude Code (CLI): Run claude mcp add --transport http affinity-mcp https://mcp.affinity.co/mcp, then open Claude Code and run /mcp, press Enter on the affinity-mcp entry, and authorize via browser.Full guide: developer.affinity.co/pages/mcp/claude
Auth: OAuth (no API key needed). Works on the Free plan and up — no developer mode or special setup.
  1. Open ChatGPT and click “Plugins” in the left sidebar (ChatGPT renamed Apps to Plugins in July 2026).
  2. Search for “Affinity” and select it.
  3. Click “Connect”, then “Sign in with Affinity” to start the OAuth flow.
  4. Click “Start chat” to begin using Affinity in ChatGPT.
In future chats: just mention “in Affinity” naturally, or click the + button → More → Affinity.Full guide: developer.affinity.co/pages/mcp/chatgpt
Auth: API key (generate in Task 4). Requires an active GitHub Copilot subscription for CLI and VS Code variants.Open Copilot’s MCP configuration:
  • Studio: Tools page → “Add a tool” → “New tool” → “Model Context Protocol”
  • CLI: Run /mcp add
  • VS Code: Command Palette → “MCP: Add Server”
Then enter:
  • Server name: affinity-mcp
  • Server URL: https://mcp.affinity.co/mcp
  • Authentication type: API key (Header)
  • Header name: Authorization
  • API key value: Bearer your_api_key_here
Copilot chat on github.com, copilot.com, and the Copilot mobile apps don’t yet support remote MCP servers.
Full guide: developer.affinity.co/pages/mcp/copilot
Auth: OAuth (automatic) or Bearer token (API key from Task 4). Requires Notion Business or Enterprise plan, plus your workspace Owner has to enable custom MCP servers in Settings → Notion AI → AI Connectors.Once that’s enabled, end-user setup:
  1. In Notion’s left sidebar, find the “Agents” section and click “New Agent”.
  2. Click “Create blank” in the top right.
  3. In the Tools and access section, click “Add connection”, then “Add custom MCP”.
  4. Configure:
    • MCP server URL: https://mcp.affinity.co/mcp
    • Name: Affinity
    • Authentication: OAuth (automatic) or Bearer token (paste your API key)
  5. Click “Connect”, then “Save” in the top right.
The agent appears under Agents. Open it and test.Full guide: developer.affinity.co/pages/mcp/notion
Auth: API key (generate in Task 4). Gemini web and mobile do not currently support MCP — CLI only.Open your terminal and run, substituting your API key:
Test by asking Gemini CLI a query against Affinity.Full guide: developer.affinity.co/pages/mcp/gemini
Any MCP-compatible client supporting custom headers can connect to Affinity. You’ll need:
  • Server URL: https://mcp.affinity.co/mcp
  • Authentication: Authorization: Bearer your_api_key_here (use the API key from Task 4)
For a comprehensive list of MCP-compatible tools, see the official MCP clients registry at modelcontextprotocol.io.Full guide: developer.affinity.co/pages/mcp/other-clients

​
Expected Outcome

Your AI client is connected to Affinity and can see Affinity-specific tools in its tool list.
Once you’re connected, you can jump to Claude or ChatGPT from Affinity itself: go to Ascend → Agents and open the Affinity MCP card, which also has a few starter prompts.

​
Task 6: Run Your First Query

​
Context

The best way to confirm the connection works is to ask a simple question that requires CRM data.

​
Action

Try one of these starter prompts in your AI client:
  • “What are the open deals in my pipeline?”
  • “Find the person profile for [name] and summarize our last 5 interactions.”
  • “Which companies on my deals list have we not contacted in the last 90 days?”
If the AI uses its Affinity tool and returns live data, you’re connected. If the AI says it doesn’t have access, double-check the connection in your client’s settings.

​
Expected Outcome

A successful round-trip query confirms your setup is working end-to-end.

​
📚 Help Center

​
Task 7: Try the Capability Areas

​
Context

Affinity’s MCP server exposes more than 50 tools, and it can both read and write. Try a query from each area to get a feel for what’s possible.

​
Action

A few tools depend on features being on for your organization: note and file search need Deal Assist, and meeting tools need unified events. Files are capped at 100 MB. If a tool returns an access error, check with your admin.

​
Expected Outcome

You have a working sense of what your AI tool can do with Affinity data.

​
📚 Help Center

​
Task 8: Run a Prepackaged Skill

​
Context

Five skills come with Affinity MCP. Each packages a whole Affinity workflow so you can run it from one plain-language ask.

​
Action

Ask for the outcome — you don’t need to name the skill. Your AI client picks the right one.

​
Expected Outcome

You’ve run a full workflow from a single request, and you know skills run with your permissions and confirm before writing to your CRM.

​
📚 Help Center

​
Task 9: Audit and Revoke Unused Access

​
Context

API keys and OAuth connections are like passwords. Audit them periodically; revoke anything you don’t actively use. Where you revoke depends on how the client authenticates.

​
Action

For API-key-based clients (Copilot, Gemini, Notion Bearer mode, other clients):
  1. Go to Settings → Manage Apps.
  2. Review the keys listed there.
  3. Revoke any unused keys via the row action. Revoked keys stop working immediately.
For OAuth-based clients (Claude, ChatGPT, Notion OAuth):
  1. Disconnect from inside the AI client’s own settings (e.g., Claude → Settings → Connectors → Affinity → Disconnect).
  2. An admin can also switch an OAuth client off for the whole organization at Settings → Affinity MCP. This disconnects everyone who connected that client through OAuth.
If you suspect a credential has leaked, revoke it immediately — then create a new one for the legitimate client.

​
Expected Outcome

Only active, in-use credentials retain access to your Affinity data.

​
📚 Help Center

​
Task 10: Go Deeper

​
Context

The dev docs cover everything beyond the user-friendly setup: full tool schemas, rate limits, OAuth flow details, and how to build custom MCP clients against Affinity.

​
Action

Explore these resources when you’re ready for more:

​
Expected Outcome

You know where to look when you need deeper technical details.

​
Common Questions

Q: Does using MCP send my CRM data to OpenAI / Anthropic? Your AI client sends data to its own model provider (e.g., Claude Desktop sends to Anthropic). Affinity itself doesn’t ship your data anywhere — it just answers tool calls from your authorized agents. Affinity sees only those structured tool calls, not your prompts, and the MCP server is stateless. Review your AI client’s privacy policy for what they do with the data they see. Q: Can my AI write to Affinity, or just read? Both. It can update fields, add records to lists, create notes and reminders, edit and delete notes, log interactions, upload files, create companies, people, opportunities, lists, and fields, delete records, and merge duplicate people and companies. Deletes and merges always wait for your explicit confirmation; most clients also ask before other writes. To keep a connection read-only, uncheck the write scope when you authorize it. Q: I’m on the Essential plan — can I get MCP? Not currently. MCP is on Scale, Advanced, and Enterprise. Contact your account manager about upgrading. Q: My admin has switched MCP off for my client or role. Can I still use AI features? You can still use Affinity’s built-in AI chat (no MCP required) — see Getting started with AI chat. MCP is for connecting external AI tools. Q: How do I know which tools my AI is calling? Most MCP-compatible clients (Claude, ChatGPT, Notion, etc.) surface tool calls in the chat UI — you can see exactly which Affinity API was queried.

​
Where to Go Next

🎉 You’ve completed Tier 1. ➡️ Move to Tier 2: Building Confidence to learn saved views, keyboard shortcuts, team collaboration, and data quality.