Skip to main content
How-to — fix common Affinity MCP issues.
Most MCP issues fall into a few buckets: authentication, permissions, or a feature that isn’t enabled for your org. Work through the section that matches your symptom.

​
”Access denied” or “unauthorized” when connecting (OAuth)

The most common cause is not on your end:
  • An admin disabled your client. Check that your AI client is enabled under Affinity → Settings → Affinity MCP (this setting applies to OAuth connections), or ask your admin. If an admin turned your client off, your existing connection stopped working too; once it’s back on, connect again.
  • Your plan doesn’t include MCP. MCP requires Scale, Advanced, or Enterprise. Confirm under Settings → Billing.
  • Your client doesn’t support OAuth. Copilot and Gemini use an API key instead — see Authentication.
If all three check out, disconnect the connector in your AI client and re-authorize from scratch.

​
”Authentication failed” / 401 (API key)

  • Copy the entire key, including any trailing characters.
  • The header must be exactly Authorization: Bearer <your-key> — one space after Bearer, no quotes, no extra whitespace.
  • Confirm the key hasn’t been revoked under Settings → Manage Apps. Revoked keys show Revoked there; if yours is, create a new key and update the client.

​
The client shows as connected, but every request fails

Some AI clients (Claude, for example) can keep showing Affinity as “connected” after the connection has stopped working. Disconnect Affinity in your AI client’s settings and connect again.

​
A saved prompt stops working after an update

If a saved prompt or instruction names a specific Affinity tool and that tool is later renamed, the client may report an unknown tool. Describe what you want in plain language instead of naming tools, and the client will pick the right one.

​
Your AI client doesn’t show the Affinity tools

  • Restart or refresh the client — some load the tool list only on startup.
  • Confirm the connection shows as connected or healthy in the client’s settings (Claude Code: /mcp; Copilot CLI: /mcp show).
  • Don’t see the delete, merge, or note-editing tools? They were added on September 24, 2026. Restart your AI client or start a new session to load them. If they still don’t appear, you or your AI client’s admin may have switched them off in the client’s tool settings.

​
Tool calls return “permission” errors after connecting

Tool calls run with your Affinity permissions. If you can’t do something directly in Affinity, MCP can’t either — ask your admin for access to the relevant list or a role change. (Reminder updates and deletes also require you to be the reminder’s creator or owner. You can edit or delete only notes you created, notes with @mentions can’t be edited, global (Affinity-enriched) companies can’t be deleted, and merging people requires an org admin with the Manage Duplicates permission.)

​
Meeting tools return an access error

get_meetings and related tools require your org to be onboarded to Affinity’s unified events feature. If you see an access error, contact your Affinity admin or CSM.

​
Note or file search returns nothing

search_notes and search_files require Deal Assist to be enabled for your org. An empty result can mean there were no matches — or that Deal Assist isn’t enabled. Check with your admin.

​
Connection drops or times out

  • Check your internet connection.
  • On a corporate VPN, make sure it allows traffic to Affinity’s API (api.affinity.co).

​
Still stuck?

See the developer troubleshooting guide at developer.affinity.co/pages/mcp/troubleshooting, or contact Affinity support.