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
    }
  }
}

Field	Type	Description
`jsonrpc`	`"2.0"`	JSON-RPC version (always `"2.0"`)
`id`	`string`	Client-generated request ID for matching responses
`method`	`string`	MCP method — `"tools/call"` for tool execution, `"tools/list"` for discovery
`params.name`	`string`	The tool to execute (e.g., `"list_meta_campaigns"`)
`params.arguments`	`object`	Tool 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

Getting Started

Concepts

Sources

MCP Protocol

MCP Protocol

How it works

Request format

Response format

Error responses

Tool discovery

Stateless design

​MCP Protocol

​How it works

​Request format

​Response format

​Error responses

​Tool discovery

​Stateless design

MCP Protocol

How it works

Request format

Response format

Error responses

Tool discovery

Stateless design