Skip to main content
The Callingbox MCP server exposes the public /v1 API as Model Context Protocol tools. Point any MCP client at it with your API key and your agent can place phone calls and manage phone numbers through natural language.

​
Connect your MCP client

Official MCP URL: https://mcp.callingbox.io/mcp
  1. Create an API key in the dashboard under Keys.
  2. Add the server to your MCP client’s configuration:
{
  "mcpServers": {
    "callingbox-mcp": {
      "url": "https://mcp.callingbox.io/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_api_key_here"
      }
    }
  }
}
The Authorization header is required on every request. The MCP server is stateless and forwards your key to the Callingbox backend on each tool call.

​
Tools

​
Calls

ToolDescription
create_callPlace an outbound AI phone call. Returns the created call record immediately.
list_callsList calls for the authenticated organization.
get_callFetch a call by ID with status, result, and returns.
get_call_transcriptFetch the ordered transcript segments and a rendered plain-text transcript for a call.
wait_for_callPoll an in-progress call until it reaches a terminal status.
make_call_and_waitPlace a call and return the final result in one shot. The most useful tool for agents.

​
Numbers

ToolDescription
list_numbersList phone numbers owned by your organization.
search_available_numbersSearch purchasable numbers by country, area code, and type.
purchase_numberBuy an available number.
Webhook endpoints can be managed via the dashboard or the public API.

​
Build your own agent

Any MCP-compatible client library works. Here’s a minimal example using mcp-use and OpenAI: 
import { MCPClient, MCPAgent } from "mcp-use";
import { ChatOpenAI } from "@langchain/openai";

const client = MCPClient.fromDict({
  mcpServers: {
    callingbox: {
      url: "https://mcp.callingbox.io/mcp",
      headers: { Authorization: `Bearer ${process.env.CALLINGBOX_API_KEY}` },
    },
  },
});

const agent = new MCPAgent({
  llm: new ChatOpenAI({ model: "gpt-4o" }),
  client,
  maxSteps: 10,
});

const result = await agent.run(
  "Call +14155551234, ask if they have reservations available for 4 people on Friday at 7pm, and extract the answer.",
);

console.log(result);
The LLM client picks make_call_and_wait, passes the appropriate prompt and returns schema, and waits for the call to complete before returning.
The MCP server currently exposes a prompt-centric shape for convenience. It accepts a prompt and returns in the tool call and handles the translation to CallingBox’s agent-based /v1/calls under the hood. For full control (persona, tools, reusable instructions, inbound routing), use the Python or TypeScript SDK and the agents API directly.