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

<Tabs>
  <Tab title="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>

  <Tab title="Claude Code (Windows)">
    Logs are written per session to `%USERPROFILE%\.claude\debug\`.
  </Tab>

  <Tab title="Claude Desktop (macOS)">
    ```bash theme={null}
    tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
    ```
  </Tab>

  <Tab title="Claude Desktop (Windows)">
    Logs are located at `%APPDATA%\Roaming\Claude\logs`.
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

***

## Common issues

<AccordionGroup>
  <Accordion title="&#x22;Authentication failed&#x22; 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>

  <Accordion title="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>

  <Accordion title="&#x22;Connection refused&#x22; 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>

  <Accordion title="&#x22;Tool not found&#x22; errors">
    **Cause:** The MCP server may have crashed or failed to start.

    **Fix:** Check the logs for startup errors.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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](/pages/mcp/supported-clients) 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>

  <Accordion title="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>

  <Accordion title="`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.
  </Accordion>
</AccordionGroup>

***

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

<Tabs>
  <Tab title="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>

  <Tab title="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
    ```
  </Tab>
</Tabs>