This document provides a complete reference for all tools available through the AffinityBots MCP Server.

Authentication

All requests require a valid API key passed as a Bearer token:

Authorization: Bearer ab_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create API keys in Settings → API Keys.

Agent Tools

affinitybots_list_agents

List all AI agents accessible to you.

Parameters:

Name	Type	Required	Default	Description
`limit`	number	No	20	Maximum agents to return (max: 100)
`offset`	number	No	0	Number of agents to skip for pagination

Response:

{
  "agents": [
    {
      "id": "uuid",
      "name": "Sales Assistant",
      "description": "Handles lead qualification",
      "model": "openai:gpt-4o",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-02-01T15:30:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

affinitybots_get_agent

Get detailed information about a specific agent.

Parameters:

Name	Type	Required	Description
`agent_id`	string	Yes	The unique ID of the agent

Response:

{
  "id": "uuid",
  "name": "Sales Assistant",
  "description": "Handles lead qualification",
  "model": "openai:gpt-4o",
  "system_prompt": "You are a helpful sales assistant...",
  "capabilities": {
    "mcp_servers": ["hubspot", "gmail"],
    "memory_enabled": true,
    "knowledge_base_enabled": true,
    "web_search_enabled": false,
    "image_generation_enabled": false
  },
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-02-01T15:30:00Z"
}

affinitybots_chat

Send a message to an agent and receive a response.

Parameters:

Name	Type	Required	Description
`agent_id`	string	Yes	The unique ID of the agent to chat with
`message`	string	Yes	The message to send
`thread_id`	string	No	Thread ID to continue an existing conversation

Response:

{
  "thread_id": "thread_uuid",
  "agent_id": "agent_uuid",
  "agent_name": "Sales Assistant",
  "response": "Based on our qualification framework, here are the key steps..."
}

[!TIP] Save the thread_id from the response to continue the conversation in future calls.

affinitybots_list_threads

List conversation threads for an agent or all agents.

Parameters:

Name	Type	Required	Default	Description
`agent_id`	string	No	-	Filter threads by agent. Omit for all agents.
`limit`	number	No	20	Maximum threads to return (max: 100)

Response:

{
  "threads": [
    {
      "thread_id": "thread_uuid",
      "agent_id": "agent_uuid",
      "created_at": "2024-02-01T10:00:00Z",
      "updated_at": "2024-02-01T10:30:00Z"
    }
  ],
  "total": 1
}

affinitybots_get_thread

Get the full conversation history of a thread.

Parameters:

Name	Type	Required	Description
`thread_id`	string	Yes	The unique ID of the thread

Response:

{
  "thread_id": "thread_uuid",
  "agent_id": "agent_uuid",
  "messages": [
    {
      "role": "user",
      "content": "What's the best way to qualify leads?"
    },
    {
      "role": "assistant",
      "content": "There are several effective frameworks for lead qualification..."
    }
  ],
  "created_at": "2024-02-01T10:00:00Z",
  "updated_at": "2024-02-01T10:30:00Z"
}

Workflow Tools

affinitybots_list_workflows

List all workflows accessible to you.

Parameters:

Name	Type	Required	Default	Description
`limit`	number	No	20	Maximum workflows to return (max: 100)
`offset`	number	No	0	Number of workflows to skip
`active_only`	boolean	No	false	Only return activated workflows

Response:

{
  "workflows": [
    {
      "id": "uuid",
      "name": "Content Approval",
      "description": "Reviews and approves marketing content",
      "type": "sequential",
      "is_active": true,
      "created_at": "2024-01-20T09:00:00Z",
      "updated_at": "2024-02-05T14:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Workflow Types:

sequential - Tasks run in a linear chain
orchestrator - Manager agent delegates to worker agents

affinitybots_get_workflow

Get detailed information about a workflow.

Parameters:

Name	Type	Required	Description
`workflow_id`	string	Yes	The unique ID of the workflow

Response:

{
  "id": "uuid",
  "name": "Content Approval",
  "description": "Reviews and approves marketing content",
  "type": "sequential",
  "is_active": true,
  "tasks": [
    {
      "id": "task_uuid",
      "name": "Review Content",
      "description": "Initial content review",
      "assistant_id": "agent_uuid"
    },
    {
      "id": "task_uuid_2",
      "name": "Final Approval",
      "description": "Manager approval step",
      "assistant_id": "agent_uuid_2"
    }
  ],
  "triggers": [
    {
      "id": "trigger_uuid",
      "type": "manual",
      "name": "Manual Trigger"
    },
    {
      "id": "trigger_uuid_2",
      "type": "webhook",
      "name": "API Webhook"
    }
  ],
  "created_at": "2024-01-20T09:00:00Z",
  "updated_at": "2024-02-05T14:00:00Z"
}

affinitybots_execute_workflow

Execute a workflow with input data.

Parameters:

Name	Type	Required	Description
`workflow_id`	string	Yes	The unique ID of the workflow
`input`	string	Yes	Input text/data for the workflow
`trigger_id`	string	No	Specific trigger to use (defaults to manual)

Response:

{
  "run_id": "run_uuid",
  "workflow_id": "workflow_uuid",
  "workflow_name": "Content Approval",
  "status": "running",
  "message": "Workflow execution started. Use affinitybots_get_run_status to check progress."
}

[!NOTE] Workflow execution is asynchronous. Use affinitybots_get_run_status to poll for completion.

affinitybots_get_run_status

Check the status and output of a workflow run.

Parameters:

Name	Type	Required	Description
`run_id`	string	Yes	The unique ID of the workflow run

Response:

{
  "run_id": "run_uuid",
  "workflow_id": "workflow_uuid",
  "workflow_name": "Content Approval",
  "status": "completed",
  "input": {
    "message": "Review the Q4 marketing report"
  },
  "output": {
    "result": "Content approved with minor revisions...",
    "task_outputs": [...]
  },
  "error": null,
  "started_at": "2024-02-06T10:00:00Z",
  "completed_at": "2024-02-06T10:02:30Z"
}

Status Values:

pending - Queued, not started
running - Currently executing
completed - Finished successfully
failed - Finished with error

Error Responses

All errors follow this format:

{
  "error": "Error message description"
}

Common Errors

HTTP Status	Error	Description
401	`Invalid API key`	Key doesn't exist or is malformed
401	`API key has been revoked`	Key was deleted by owner
401	`API key has expired`	Key passed expiration date
403	`Tool not allowed for scope`	Key scope doesn't include this tool
404	`Agent not found`	Agent doesn't exist or isn't yours
404	`Workflow not found`	Workflow doesn't exist or isn't yours
404	`Thread not found`	Thread doesn't exist or isn't yours
429	`Rate limit exceeded`	Too many requests per minute
500	`Internal server error`	Server-side error

Rate Limiting

Requests are rate-limited per API key:

Plan	Limit
Free	60/min
Starter	60/min
Pro	300/min
Enterprise	1000/min

When rate limited, wait and retry with exponential backoff.

Best Practices

Thread Reuse: Always save and reuse thread_id for ongoing conversations
Pagination: Use limit and offset for large lists
Scoped Keys: Create keys with only the scope you need
Error Handling: Always handle error responses gracefully
Async Workflows: Poll get_run_status instead of waiting

MCP Reference

Authentication

Agent Tools

affinitybots_list_agents

affinitybots_get_agent

affinitybots_chat

affinitybots_list_threads

affinitybots_get_thread

Workflow Tools

affinitybots_list_workflows

affinitybots_get_workflow

affinitybots_execute_workflow

affinitybots_get_run_status

Error Responses

Common Errors

Rate Limiting

Best Practices