Connecting Claude Desktop

Overview

Claude Desktop supports MCP through its claude_desktop_config.json file. This guide walks you through connecting Claude Desktop to your af-gemini-connect platform.

Prerequisites

• Claude Desktop installed (download)
• An active API key with mcp:access scope (generate one here)
• Your platform URL (e.g., https://api.v2.affinitydesign.ca)

Step-by-Step Setup

1. Locate the Config File

The config file location depends on your OS:

2. Edit the Config File

Add your platform as an MCP server:

{
  "mcpServers": {
    "af-platform": {
      "type": "http",
      "url": "https://api.v2.affinitydesign.ca/mcp/http",
      "headers": {
        "X-API-Key": "afk_YOUR_KEY_HERE"
      }
    }
  }
}

Important: Use your actual API key, not the placeholder. The key is scoped to one client — all Claude interactions will operate within that client's data.

3. Restart Claude Desktop

Fully quit and reopen Claude Desktop for the config to take effect.

4. Verify the Connection

In Claude Desktop, look for the tools indicator (usually a hammer icon or "Tools" label). Click it to see the list of available tools from your platform.

You can also test by asking:

"What tools do you have access to?"

Claude should list the plugins enabled for your API key.

Using Multiple Clients

If you manage multiple clients, you have two options:

Option A: One Config Per Client

Switch between clients by editing the config file and restarting Claude:

{
  "mcpServers": {
    "client-acme": {
      "type": "http",
      "url": "https://api.v2.affinitydesign.ca/mcp/http",
      "headers": {
        "X-API-Key": "afk_ACME_KEY"
      }
    },
    "client-globex": {
      "type": "http",
      "url": "https://api.v2.affinitydesign.ca/mcp/http",
      "headers": {
        "X-API-Key": "afk_GLOBEX_KEY"
      }
    }
  }
}

Claude will see tools from both clients. Be explicit about which client you're working with in your prompts.

Option B: Admin JWT (Agency-Wide)

Use an admin Bearer token instead of a client API key. This requires passing ?clientId=... in the URL for each request, which Claude Desktop does not support well. Option A is recommended.

Troubleshooting

"Failed to connect to MCP server"

• Verify your API key is active and has the mcp:access scope
• Check that the URL is correct (must end in /mcp/http for HTTP transport)
• Ensure there are no trailing commas in your JSON
• Check Claude Desktop logs for detailed error messages

Tools not appearing

• Restart Claude Desktop completely (not just the window)
• Verify the key's plugin restrictions aren't blocking everything
• Check that the client is Active in the admin dashboard

"Unauthorized" errors during tool use

• The key may have been revoked or the client deactivated
• Some tools require additional scopes beyond mcp:access (e.g., outbound:call for initiating calls)

Tips for Effective Use

• Be specific: "Check GHL for leads created today" works better than "do CRM stuff"
• Chain operations: "Find the contact, book an appointment for tomorrow at 2pm, then send them a confirmation SMS"
• Verify before acting: Ask Claude to show you what it plans to do before executing destructive operations
• Use resources: Reference assets via asset://{assetRef} and knowledge docs via knowledge://... URIs