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 page for help obtaining one
- UV Python package manager
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.
Claude CLI
Claude Desktop
Gemini CLI
Copilot CLI
Copilot (VS Code)
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.claude mcp add affinity-mcp \
--scope user \
--transport stdio \
--env AFFINITY_API_KEY=your_api_key_here \
-- uvx affinity-mcp
--scope user to register the server for the current project only.Verify the server is connected: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
~/.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
-
Run Copilot CLI
-
Add server using /mcp
-
Run /mcp add
-
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:
*
-
Press CTRL + S to save.
-
Verify configurations
- Run /mcp show and you should see the server is connected.
- Open ~/.copilot/mcp_config.json to verify:
{
"mcpServers": {
"affinity-mcp": {
"tools": [
"*"
],
"type": "stdio",
"command": "uvx",
"args": [
"affinity-mcp"
],
"env": {
"AFFINITY_API_KEY": "your_api_key_here"
}
}
}
}
- 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"
}
}
}
}
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:
"env": {
"AFFINITY_API_KEY": "your_api_key_here",
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317"
}
OTEL_EXPORTER_OTLP_ENDPOINT is not set, telemetry export is disabled and the server operates
normally without it.
Other Clients
See MCP Clients for a full list of compatible clients.
