Developer Guide

MCP Server

Connect AI agents (Claude, Cursor, or custom integrations) to Call Camp Studio via the Model Context Protocol. The MCP server provides 12 tools and 7 resources for managing campaigns, records, calls, and analytics.

Overview

The Call Camp Studio MCP server implements the Model Context Protocol specification, enabling AI assistants to securely interact with your campaign data. All operations are scoped to the authenticated user's client — meaning each API token sees only its own data.

12 Tools

Create records, initiate calls, manage call orders, and view transcripts.

7 Resources

Read campaign stats, outcomes, costs, and detailed record profiles.

Secure

Bearer token auth with role-based permissions and client data isolation.

Authentication & Access

The MCP server uses Bearer token authentication. Each token resolves to a specific User → Client → Role chain, which determines both data scope and available permissions.

Generate an API Token

Go to Profile → Security → Generate Token. Copy the token value — you will need it for the MCP configuration.

Configure your MCP client

Use the token in the Authorization: Bearer <token> header.

Data scope

All data queries are automatically filtered to the client associated with your user account. Master users can see cross-client data.

Connection Setup

MCP Endpoint: https://callcamp.ai/mcp

Claude Desktop

Claude Desktop only supports local stdio servers. Since our server is hosted over HTTP, you must use a bridge like mcp-remote or server-proxy to translate the protocol:

{
  "mcpServers": {
    "call-camp-studio": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://callcamp.ai/mcp",
        "--header", "Authorization: Bearer YOUR_API_TOKEN"
      ]
    }
  }
}

Do not use curl or http command: These tools cannot maintain the persistent JSON-RPC session required for tools and resources to function correctly.

Cursor / IDE

Add to your .cursor/mcp.json or equivalent MCP config:

{
  "mcpServers": {
    "call-camp-studio": {
      "url": "https://callcamp.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Cursor natively supports HTTP MCP servers, so a bridge is not required there.

Tools Reference

Tools are actions that can create, update, or read data. Each tool returns a JSON text response.

Record Tools

TOOLlist-records

List and search records for the current client. Supports pagination and filtering.

Parameter	Type	Required	Description
search	string	No	Search by name, email, or phone number
status	string	No	Filter: active, inactive, archived
recordTypeUuid	string	No	Filter by record type UUID
page	number	No	Page number (default: 1)
limit	number	No	Results per page (max 100)

TOOLget-record

Get a single record by UUID with its type and related counts.

Parameter	Type	Required	Description
uuid	string	Yes	UUID of the record

TOOLcreate-record

Create a new record (contact) for the current client.

Parameter	Type	Required	Description
name	string	Yes	Full name
phoneNumber	string	Yes	International format (e.g., +1234567890)
recordTypeUuid	string	Yes	UUID of the record type
email	string	No	Email address
firstName	string	No	First name
lastName	string	No	Last name
country	string	No	Country code (e.g., US, AE)
parameters	object	No	Custom key-value parameters

TOOLupdate-record

Update an existing record by UUID.

Parameter	Type	Required	Description
uuid	string	Yes	UUID of the record to update
name	string	No	Updated full name
email	string	No	Updated email
phoneNumber	string	No	Updated phone number
status	string	No	Updated status
firstName	string	No	Updated first name
lastName	string	No	Updated last name
parameters	object	No	Updated custom parameters

Call Order Tools

TOOLlist-call-orders

List call orders for the current client with optional filtering.

Parameter	Type	Required	Description
campaignUuid	string	No	Filter by campaign UUID
recordUuid	string	No	Filter by record UUID
status	string	No	Filter: planned, busy, contacted, canceled, do_not_call, rescheduled, failed
page	number	No	Page number (default: 1)
limit	number	No	Results per page (max 100)

TOOLcreate-call-order

Create a call order — assigns a record to a campaign for calling.

Parameter	Type	Required	Description
recordUuid	string	Yes	UUID of the record to call
campaignUuid	string	Yes	UUID of the campaign
callType	string	No	Call type: phone_out, phone_in, web
scheduledTime	string	No	ISO-8601 scheduled time
instructions	string	No	Special instructions

TOOLupdate-call-order-status

Update the status of a call order.

Parameter	Type	Required	Description
uuid	string	Yes	UUID of the call order
status	string	Yes	New status: planned, busy, contacted, canceled, do_not_call, rescheduled, failed

Call Tools

TOOLinitiate-callcalls.manage

Initiate an outbound phone call for a call order. Validates balance, campaign status, and phone number before calling.

Parameter	Type	Required	Description
callOrderUuid	string	Yes	UUID of the call order

TOOLget-call-detailscalls.view

Get full call details including campaign, record, outcomes, and cost breakdown.

Parameter	Type	Required	Description
callUuid	string	Yes	UUID of the call

TOOLget-call-recordingcalls.view

Get the recording URL for a completed call (MP3 format).

Parameter	Type	Required	Description
callUuid	string	Yes	UUID of the call

TOOLget-call-transcriptcalls.view

Get the full transcript of a call with role labels and call summary.

Parameter	Type	Required	Description
callUuid	string	Yes	UUID of the call

TOOLget-call-outcomescalls.view

Get all AI-extracted outcomes from a specific call.

Parameter	Type	Required	Description
callUuid	string	Yes	UUID of the call

Resources Reference

Resources provide read-only analytical data. AI agents can read these to understand campaign performance before taking action.

RESOURCEcampaign-stats-list

URI:studio://campaigns/stats

Aggregated performance statistics for all client campaigns.

Response data:

Total calls, answered rate, avg duration, total cost, calls by end reason, orders by status — per campaign.

RESOURCEcampaign-stats-single

URI:studio://campaigns/{uuid}/stats

Detailed performance statistics for a specific campaign.

Response data:

Same as above, scoped to a single campaign UUID.

RESOURCEcampaign-outcomes

URI:studio://campaigns/{uuid}/outcomes

Aggregated outcome summary for a specific campaign, grouped by outcome name.

Response data:

Outcome counts and collected values grouped by AssistantOutcome name.

RESOURCErecord-outcomes

URI:studio://records/{uuid}/outcomes

Outcome summary for a specific record across all its campaigns.

Response data:

Outcome counts and values with campaign attribution.

RESOURCErecord-details

URI:studio://records/{uuid}

Full details of a record including call history, outcomes, and notes.

Response data:

Record fields, call orders with calls (status, duration, summary), latest 20 notes.

RESOURCEcampaign-cost

URI:studio://campaigns/{uuid}/cost

Cost breakdown for a specific campaign.

Response data:

Operational cost, phone cost, total price, margin, and currency.

RESOURCEtotal-cost

URI:studio://costs/total

Total cost across all campaigns for the current client.

Response data:

Aggregated costs with per-campaign breakdown.

Error Handling

When a tool encounters an error, it returns a response with isError: true and a human-readable error message. The MCP connection itself remains active.

// Error response format
{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Record not found or access denied"
  }]
}

// Common error scenarios:
// - Invalid/expired token → HTTP 401 (handled via bridge/client)
// - No client association → HTTP 403
// - Missing permission → "Forbidden: Missing required permission [calls.manage]"
// - Record not found → "Record not found or access denied"
// - Insufficient balance → "Insufficient client balance to initiate calls"

Permissions

Some tools require specific permissions based on the user's role. Admin users have all permissions automatically.

Tool	Required Permission
initiate-call	`calls.manage`
get-call-details	`calls.view`
get-call-recording	`calls.view`
get-call-transcript	`calls.view`
get-call-outcomes	`calls.view`

All other tools (records, call orders) use implicit token-based access — any valid token belonging to a user with an associated client can access them.