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

# Local MCP

> Run the Affinity MCP server locally using STDIO

## Prerequisites

* An Affinity account with API access (Scale, Advanced, or Enterprise)
* An MCP-compatible AI assistant (e.g., Claude Desktop, Copilot, Gemini CLI)
* An Affinity API key. See the [Authentication](/pages/mcp/authentication) page for help obtaining one
* [UV](https://docs.astral.sh/uv/getting-started/installation/) Python package manager

<Note>
  **Switching to the hosted MCP server?** If you currently run Affinity locally and want to move
  to the hosted server, first remove the existing `affinity-mcp` configuration from your AI
  client (consult your client's documentation for steps), then follow the appropriate guide
  under **Setup by Client**.
</Note>

<Tabs>
  <Tab title="Claude CLI">
    Run the following command with your API key filled in. The `--scope user` flag registers the server for your user account so it's available in all your projects.

    ```bash theme={null}
    claude mcp add affinity-mcp \
        --scope user \
        --transport stdio \
        --env AFFINITY_API_KEY=your_api_key_here \
        -- uvx affinity-mcp
    ```

    Omit `--scope user` to register the server for the current project only.

    Verify the server is connected:

    ```bash theme={null}
    claude mcp list
    ```

    You should see:

    ```
    affinity-mcp: uvx affinity-mcp - ✓ Connected
    ```
  </Tab>

  <Tab title="Claude Desktop">
    1. Go to **File** → **Settings** → **Developer** → **Edit Config** and open `claude_desktop_config.json`.
    2. Run `which uvx` in your terminal and copy the full path it returns.
    3. Add the following to the config, replacing the `command` with the path from the previous step and the API key with your own:

    ```json theme={null}
    {
      "mcpServers": {
        "affinity-mcp": {
          "command": "your-uvx-path-here",
          "args": ["affinity-mcp"],
          "env": {
            "AFFINITY_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```

    4. Restart Claude Desktop to apply the changes.
  </Tab>

  <Tab title="Gemini CLI">
    1. Open `~/.gemini/settings.json`.
    2. Add the server configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "affinity-mcp": {
          "command": "uvx",
          "args": ["affinity-mcp"],
          "env": {
            "AFFINITY_API_KEY": "your_api_key_here"
          },
          "trust": false
        }
      }
    }
    ```

    3. Verify with `gemini mcp list` or run `gemini` → `/mcp`. You should see:

    ```
    ✓ affinity-mcp: uvx affinity-mcp (stdio) - Connected
    ```
  </Tab>

  <Tab title="Copilot CLI">
    1. **Run Copilot CLI**

    2. **Add server using /mcp**

       1. Run **/mcp add**

       2. Add the server information:
          * **Server Name**: `affinity-mcp`
          * **Server Type**: STDIO
          * **Command**: `uvx affinity-mcp`
          * **Environment Variables**: `{"AFFINITY_API_KEY": "your_api_key_here"}`
          * **Tools**: `*`

       3. Press CTRL + S to save.

    3. **Verify configurations**

       1. Run **/mcp show** and you should see the server is connected.
       2. Open **\~/.copilot/mcp\_config.json** to verify:

       ```json theme={null}
       {
         "mcpServers": {
           "affinity-mcp": {
             "tools": [
               "*"
             ],
             "type": "stdio",
             "command": "uvx",
             "args": [
               "affinity-mcp"
             ],
             "env": {
               "AFFINITY_API_KEY": "your_api_key_here"
             }
           }
         }
       }
       ```
  </Tab>

  <Tab title="Copilot (VS Code)">
    1. Open the Command Palette and select **MCP: Add Server…**
    2. Select **Command (stdio)**
    3. Enter: `uvx affinity-mcp`
    4. Choose **affinity-mcp** as the Server ID.
    5. Select **Workspace**.
    6. Open the generated `.vscode/mcp.json` and add your API key to the `env` block:

    ```json theme={null}
    {
      "inputs": [],
      "servers": {
        "affinity-mcp": {
          "command": "uvx",
          "args": ["affinity-mcp"],
          "env": {
            "AFFINITY_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## OpenTelemetry (Optional)

The server supports OpenTelemetry tracing. To export telemetry data to an OTLP-compatible
collector, set the `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable alongside your API key in
your client config. Example:

```json theme={null}
"env": {
  "AFFINITY_API_KEY": "your_api_key_here",
  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
}
```

If `OTEL_EXPORTER_OTLP_ENDPOINT` is not set, telemetry export is disabled and the server operates
normally without it.

## Other Clients

See [MCP Clients](https://modelcontextprotocol.io/clients) for a full list of compatible clients.