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

# Troubleshooting

> Diagnose and fix common issues with the Affinity MCP Server

## Viewing server logs

If the server isn't working as expected, check the logs first.

> [tab] Claude Code (macOS/Linux)
>
> Logs are written per session to `~/.claude/debug/`. The `latest` symlink always points to the most recent session:
>
> ```bash theme={null}
> tail -n 50 -F ~/.claude/debug/latest
> ```

> [tab] Claude Code (Windows)
>
> Logs are written per session to `%USERPROFILE%\.claude\debug\`.

> [tab] Claude Desktop (macOS)
>
> ```bash theme={null}
> tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
> ```

> [tab] Claude Desktop (Windows)
>
> Logs are located at `%APPDATA%\Roaming\Claude\logs`.

> [tab] ChatGPT
>
> ChatGPT does not expose MCP server logs directly. If Affinity tools aren't appearing or calls
> are failing, try these steps:
>
> 1. Open **Settings** → **Apps** and check that the Affinity app shows a connected status.
> 2. If the app shows an error or is disconnected, click the app and press **Disconnect**, then
>    reconnect and reauthorize.
> 3. Verify the **MCP Server URL** is set to `https://mcp.affinity.co/mcp`.
> 4. If the issue persists, delete the app and recreate it following the setup guide.

***

## Common issues

> [accordion] "Authentication failed" or 401 errors
>
> **Cause:** The `AFFINITY_API_KEY` is missing, invalid, or has extra spaces or quotes around it.
>
> **Fix:** Double-check the environment variable value in your client config. The key should be a plain string with no surrounding quotes or whitespace.

> [accordion] API key shown as 'invalid' or returning 401 errors
>
> * Confirm you copied the full key, including any trailing characters.
> * Confirm the `Authorization` header uses the exact format `Bearer <your-key>` (one space, no quotes around the value).
> * In **Affinity → Settings → Manage Apps**, verify the key hasn't been rotated or revoked.

> [accordion] "Connection refused" or timeout errors
>
> **Cause:** The server cannot reach `api.affinity.co`.
>
> **Fix:**
>
> * Check your internet connection.
> * If you're on a corporate VPN, ensure it allows traffic to Affinity's API.

> [accordion] "Tool not found" errors
>
> **Cause:** The MCP server may have crashed or failed to start.
>
> **Fix:** Check the logs for startup errors.

> [accordion] My AI client doesn't see the Affinity tool
>
> * Refresh / restart the AI client (some clients only refresh the tool list on startup).
> * In the client, verify the MCP server status is "connected" or "healthy".
> * For Copilot CLI, run `/mcp show`. For Claude Code, run `/mcp`.

> [accordion] OAuth flow returned 'unauthorized' or 'access denied'
>
> Most common cause: your Affinity admin has disabled the AI client you're connecting from, or your plan doesn't include MCP access.
>
> * In Affinity, go to **Settings → Affinity MCP** and confirm your client is enabled.
> * Confirm your plan is **Scale**, **Advanced**, or **Enterprise**.
> * Affinity may not support OAuth for the AI client you're using. Check
>   [Supported Clients](https://developer.affinity.co/pages/mcp/supported-clients.md) to see which auth methods are available
>   for your client, and use API key auth if OAuth isn't supported.
> * If all of the above check out, disconnect the AI client and re-authenticate from scratch.

> [accordion] OAuth works but tool calls return permission errors
>
> MCP tool calls run with your Affinity user's permissions. If you can't read a list or create a note in Affinity directly, MCP can't either. Ask your admin to grant the needed list / role access.

> [accordion] `get_meetings` returns an access error
>
> **Cause:** Your organization hasn't been onboarded to Affinity's unified events feature, which is required for the meetings API.
>
> **Fix:** Contact your Affinity CSM to request access.

***

## Debugging with MCP Inspector

You can use the MCP Inspector to test tools and debug the server interactively in your browser.
The inspector lets you list available tools, call them with custom arguments, and inspect
responses. Useful for verifying the server is working before connecting a full AI client.

> [tab] Local server
>
> ```bash theme={null}
> npx @modelcontextprotocol/inspector uvx affinity-mcp
> ```
>
> Set the `AFFINITY_API_KEY` environment variable before running, or pass it inline:
>
> ```bash theme={null}
> AFFINITY_API_KEY=your_api_key_here npx @modelcontextprotocol/inspector uvx affinity-mcp
> ```

> [tab] Hosted server
>
> ```bash theme={null}
> npx @modelcontextprotocol/inspector
> ```
>
> In the Inspector UI, set the transport to **HTTP** and enter the server URL:
>
> ```
> https://mcp.affinity.co/mcp
> ```
>
> Add an `Authorization` header with your API key:
>
> ```
> Authorization: Bearer your_api_key_here
> ```


## Related topics

- [Notion](https://developer.affinity.co/pages/mcp/notion.md)
- [Gemini](https://developer.affinity.co/pages/mcp/gemini.md)
- [Copilot](https://developer.affinity.co/pages/mcp/copilot.md)
- [Claude](https://developer.affinity.co/pages/mcp/claude.md)
- [ChatGPT](https://developer.affinity.co/pages/mcp/chatgpt.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.