> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adside.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Protocol

> How JSON-RPC 2.0 and the Model Context Protocol work in this API

# MCP Protocol

This API uses the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) — 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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/error-handling).

## Tool discovery

List all available tools for a source:

```bash theme={null}
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