> ## 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](https://developer.affinity.co/pages/mcp/authentication.md) 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**.

> [tab] 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] 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] 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] 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] 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"
>       }
>     }
>   }
> }
> ```

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


## Related topics

- [Troubleshooting](https://developer.affinity.co/pages/mcp/troubleshooting.md)
- [Available Tools](https://developer.affinity.co/pages/mcp/available-tools.md)
- [OAuth Apps and MCP Clients (CIMD)](https://developer.affinity.co/pages/external-api-v2/oauth-apps.md)
- [Copilot](https://developer.affinity.co/pages/mcp/copilot.md)
- [Other Clients](https://developer.affinity.co/pages/mcp/other-clients.md)


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