Skip to main content

​
MCP Protocol

This API uses the Model Context Protocol (MCP) — a standard for exposing tool-based APIs via JSON-RPC 2.0 over HTTP.

​
How it works

Each ad platform source (Meta, LinkedIn, Google Ads) exposes its operations as MCP tools. All tools for a source share a single HTTP endpoint: 
POST /{source}/mcp
The specific tool is identified by the params.name field in the JSON-RPC request body.

​
Request format

Every MCP tool call follows this structure: 
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      // tool-specific input
    }
  }
}
FieldTypeDescription
jsonrpc"2.0"JSON-RPC version (always "2.0")
idstringClient-generated request ID for matching responses
methodstringMCP method — "tools/call" for tool execution, "tools/list" for discovery
params.namestringThe tool to execute (e.g., "list_meta_campaigns")
params.argumentsobjectTool input — validated against the tool’s Zod schema

​
Response format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"campaigns\": [...], \"pagination\": {...}}"
      }
    ]
  }
}
The result.content array contains one or more content blocks. For this API, results are always type: "text" with a JSON-stringified payload in text.

​
Error responses

Tool-level errors return isError: true in the result: 
{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error listing campaigns: Invalid access token"
      }
    ],
    "isError": true
  }
}
HTTP-level errors (auth, rate limiting) return standard HTTP status codes with an error body. See Error Handling.

​
Tool discovery

List all available tools for a source: 
curl -X POST http://localhost:3100/meta/mcp \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/list"}'
Response includes each tool’s name, description, and JSON Schema input definition.

​
Stateless design

Each HTTP request creates a fresh MCP server instance — there is no session state between requests. This means:
  • No initialize handshake needed
  • No session tokens to manage
  • Each request is fully self-contained