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

# Troubleshooting Affinity MCP

> Diagnose and fix common Affinity MCP connection and permission issues.

<Note>
  **How-to** — fix common Affinity MCP issues.
</Note>

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**, or ask your admin.
* **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](https://developer.affinity.co/pages/mcp/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 rotated or revoked under **Settings → Manage Apps**.

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

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

## 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](https://developer.affinity.co/pages/mcp/troubleshooting), or contact Affinity support.