Skip to main content

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.

​
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 Settings 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. Verify your plan and your permissions
  3. (Admin) Enable MCP Agents permission for the right roles
  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 six capability areas
  8. Audit and revoke unused access
  9. 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
  • Update a field, add a note, or create a reminder — all conversationally

​
Expected Outcome

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

​
📚 Help Center

​
Task 2: Verify Your Plan and Permissions

​
Context

MCP is gated by both plan tier and a per-role permission. Confirm both before going further.

​
Action

  1. Check your plan: Go to Settings → Billing Settings. MCP is available on Scale, Advanced, and Enterprise plans. If you’re on a different plan, contact your account manager.
  2. Check your role permission: Each role in your workspace either has the “Manage MCP Agents” permission or doesn’t. To find out:
    • Go to Settings → Users and Permissions → Roles.
    • Click your role and look for the “Manage MCP Agents” toggle.
    • If it’s on, you can configure MCP for yourself. If it’s off, work with your admin (see Task 3).
End-user vs admin split. Setting up your own MCP connection is something each user does for themselves under Settings → Affinity MCP. Controlling who’s allowed to set one up is an admin function under Users & Permissions → Roles. They’re different surfaces — don’t confuse the two.

​
Expected Outcome

You know whether you can self-serve MCP, or whether you need admin help first.

​
Task 3: (Admin) Enable MCP Agents Permission for the Right Roles

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

​
Context

By default, MCP access is gated. Admins decide which roles get the “Manage MCP Agents” permission. Common patterns: enable for power users and analysts; leave disabled for read-only or contractor roles.

​
Action

  1. Go to Settings → Users and Permissions → Roles.
  2. Click into a role you want to grant MCP access to.
  3. Find the “Manage MCP Agents” permission in the permissions list.
  4. Toggle it on and save.
  5. Repeat for each role that should have access.
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

The right roles can self-serve MCP setup. Other roles are gated.

​
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 → API Keys.
  2. Click “Create new key”.
  3. Name your key after the client you’ll use (e.g., Gemini CLI, Copilot VS Code) so you can identify it when auditing later.
  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.
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:
  1. In Claude, open Settings → Connectors → Add custom connector.
  2. Enter:
    • Name: Affinity
    • Remote MCP server URL: https://mcp.affinity.co/mcp
  3. Click “Add”.
  4. Go to Customize → Connectors and click “Connect” on the Affinity row.
  5. 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 “Apps” in the left sidebar.
  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:
gemini mcp add --transport http \
  --header "Authorization: Bearer your_api_key_here" \
  affinity-mcp https://mcp.affinity.co/mcp
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.

​
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 Six Capability Areas

​
Context

Affinity’s MCP server exposes six capability areas. Try a query from each to get a feel for what’s possible.

​
Action

CapabilityTry asking
Relationship intelligence”Who at my firm has the warmest relationship with someone at [Company]?”
Pipeline management”List all opportunities in ‘Diligence’ stage with amount > $10M.”
Meetings & activity”Summarize my interactions with [Person] over the last 90 days.”
Notes & capture”Create a note on [Company]‘s profile titled ‘Q2 board observations’ with these bullets…”
Field updates”Update [Person]‘s job title to ‘VP Engineering’.”
Reminders”Remind me to follow up with [Person] next Tuesday.”

​
Expected Outcome

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

​
📚 Help Center

​
Task 8: 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 → API Keys.
  2. Review the list of keys you’ve created.
  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. You can also review the OAuth connections Affinity has issued at Settings → Affinity MCP.
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 9: 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. 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. Affinity’s MCP server supports field updates, note creation, and reminder creation. Your AI will ask for confirmation before destructive actions in most clients. Q: I’m on Starter / Free plan — can I get MCP? Not currently. MCP is on Scale, Advanced, and Enterprise. Contact your account manager about upgrading. Q: My admin disabled MCP for my 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.