AffinityBots provides an MCP server that allows you to use your agents and workflows from external applications like Claude Desktop, Cursor, Cline, or any MCP-compatible client.

This enables powerful integrations where you can:

Chat with your AI agents from your IDE
Execute workflows from external automation tools
Build custom applications using AffinityBots as the AI backend

1. Getting Started

Create an API Key

Before connecting, you'll need to create an API key:

Go to Settings → API Keys tab
Click "Create Key"
Enter a name for your key (e.g., "Claude Desktop")
Select the Access Scope:
- Agents & Workflows: Full access to both
- Agents Only: Only agent-related tools
- Workflows Only: Only workflow-related tools
Click "Create Key"
Copy the key immediately - you won't be able to see it again!

Create API Key

[!WARNING] Keep your API key secure! Treat it like a password. Never share it publicly or commit it to version control.

Rate Limits

API keys have rate limits based on your subscription plan:

Plan	Rate Limit
Free	60 requests/minute
Starter	60 requests/minute
Pro	300 requests/minute
Enterprise	1000 requests/minute

2. Connecting Your MCP Client

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "affinitybots": {
      "url": "https://affinitybots.com/api/mcp/server",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your actual API key.

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "affinitybots": {
      "url": "https://affinitybots.com/api/mcp/server",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Other MCP Clients

Any MCP client that supports Streamable HTTP transport can connect using:

URL: https://affinitybots.com/api/mcp/server
Transport: streamable-http
Authentication: Bearer token in Authorization header

3. Available Tools

Once connected, you'll have access to these tools based on your API key scope:

Agent Tools

Tool	Description
`affinitybots_list_agents`	List all your agents with their IDs, names, and configurations
`affinitybots_get_agent`	Get detailed information about a specific agent
`affinitybots_chat`	Send a message to an agent and receive a response
`affinitybots_list_threads`	List conversation threads for an agent
`affinitybots_get_thread`	Get the full conversation history of a thread

Workflow Tools

Tool	Description
`affinitybots_list_workflows`	List all your workflows with their status
`affinitybots_get_workflow`	Get workflow details including tasks and triggers
`affinitybots_execute_workflow`	Execute a workflow with input data
`affinitybots_get_run_status`	Check the status and output of a workflow run

4. Example Usage

Chatting with an Agent

In Claude Desktop or your MCP client, you can now interact with your AffinityBots agents naturally:

You: "List my AffinityBots agents"

Claude: Uses affinitybots_list_agents

Here are your agents:
1. Sales Assistant (ID: abc123) - Handles lead qualification
2. Support Bot (ID: def456) - Answers customer questions
3. Content Writer (ID: ghi789) - Creates marketing copy

You: "Ask my Sales Assistant about lead qualification best practices"

Claude: Uses affinitybots_chat with agent_id: abc123

The Sales Assistant says:

"Lead qualification best practices include:
1. BANT Framework - Budget, Authority, Need, Timeline
2. Score leads based on engagement...
[response continues]"

Executing a Workflow

You: "Run my content approval workflow with input: 'Review the Q4 marketing report'"

Claude: Uses affinitybots_execute_workflow

Workflow started! Run ID: run_xyz789
Status: running

Use affinitybots_get_run_status to check progress.

Continuing Conversations

The MCP server supports conversation threads, so you can have ongoing discussions:

You: "Chat with my Support Bot: What's your return policy?"
Claude: [creates new thread, returns response]

You: "Continue that conversation: What about international returns?"
Claude: [uses same thread_id, maintains context]

5. API Key Management

Viewing Your Keys

Go to Settings → API Keys to see all your keys with:

Key prefix (for identification)
Scope (what it can access)
Last used date
Total request count

Revoking Keys

If a key is compromised:

Go to Settings → API Keys
Find the key in the list
Click the trash icon to revoke
Create a new key if needed

Revoked keys immediately stop working - any client using that key will receive an authentication error.

6. Best Practices

Security

Rotate keys periodically - Create new keys and revoke old ones regularly
Use specific scopes - Only grant the access your application needs
Don't share keys - Each application/user should have their own key
Monitor usage - Check the "Last Used" and "Requests" columns for unusual activity

Performance

Reuse threads - For ongoing conversations, pass the thread_id to maintain context efficiently
Handle rate limits - If you hit rate limits, implement exponential backoff
Cache agent/workflow lists - Don't fetch the list every time if it doesn't change often

Error Handling

Common error responses:

Error	Cause	Solution
`Invalid API key`	Key doesn't exist or is wrong	Check the key value
`API key has been revoked`	Key was deleted	Create a new key
`API key has expired`	Key passed its expiration date	Create a new key
`Rate limit exceeded`	Too many requests	Wait and retry with backoff
`Tool not allowed for scope`	Key scope doesn't include this tool	Create key with correct scope

7. Troubleshooting

"Connection refused" or timeout

Verify the URL is correct: https://affinitybots.com/api/mcp/server
Check your internet connection
Ensure your firewall allows outbound HTTPS

"Invalid API key" but key looks correct

Make sure there are no extra spaces or newlines
Verify the key starts with ab_live_
Try creating a new key

Tools not appearing

Check your API key scope matches what you need
Restart your MCP client after configuration changes
Verify the JSON configuration syntax is valid

Need Help?

Check our Troubleshooting Guide
Contact support through the in-app chat
Visit our Community Forum

MCP Server