Setup & Installation

Prerequisites

An Affinity account with API access (Scale, Advanced, or Enterprise)
UV Python package manager
An MCP-compatible AI assistant (e.g., Claude Desktop, GitHub Copilot, Gemini CLI)
An Affinity API key — see the Authentication page for help obtaining one

Client Setup

Claude CLI
Claude Desktop
GitHub Copilot (VS Code)
Gemini CLI
ChatGPT

Run the following command with your values filled in. The --scope user flag registers the server for your user account so it’s available in all your projects.

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:

claude mcp list

You should see:

affinity-mcp: uvx affinity-mcp - ✓ Connected

Go to File → Settings → Developer → Edit Config and open claude_desktop_config.json.
Run which uvx in your terminal and copy the full path it returns.
Add the following to the config, replacing the command with the path from the previous step and the API key with your own:

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

Restart Claude Desktop to apply the changes.

Open the Command Palette and select MCP: Add Server…
Select Command (stdio)
Enter: uvx affinity-mcp
Choose affinity-mcp as the Server ID.
Select Workspace.
Open the generated .vscode/mcp.json and add your API key to the env block:

{
  "inputs": [],
  "servers": {
    "affinity-mcp": {
      "command": "uvx",
      "args": ["affinity-mcp"],
      "env": {
        "AFFINITY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Open ~/.gemini/settings.json.
Add the server configuration:

{
  "mcpServers": {
    "affinity-mcp": {
      "command": "uvx",
      "args": ["affinity-mcp"],
      "env": {
        "AFFINITY_API_KEY": "your_api_key_here"
      },
      "trust": false
    }
  }
}

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

✓ affinity-mcp: uvx affinity-mcp (stdio) - Connected

ChatGPT requires a publicly accessible URL to connect to the MCP server, so you’ll need to expose your local server using ngrok.

Enable Developer Mode in ChatGPT under Settings → Advanced → Developer Mode.
Start the MCP server locally using the MCP Inspector:

npx @modelcontextprotocol/inspector uvx affinity-mcp -e AFFINITY_API_KEY=your_api_key_here

Note the port number and auth token shown in the inspector output.

In a separate terminal, expose the server with ngrok (replace 8000 with your port):

ngrok http 8000

Copy the public URL that ngrok provides.
In ChatGPT, go to Connectors and create a new connector with:
- Name: affinity-mcp
- MCP Server URL: the ngrok public URL

Other Clients

See MCP Clients for a full list of compatible clients.

Getting Started

Reference

Prerequisites

Client Setup

Other Clients

Getting Started

Reference

​Prerequisites

​Client Setup

​Other Clients

Prerequisites

Client Setup

Other Clients