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

# Overview

> Citable's MCP server exposes your brand's data and actions to any AI agent that speaks the Model Context Protocol — Claude Desktop, Cursor, ChatGPT, or your own integrations.

Citable runs an MCP server you can connect to from any AI client that supports the [Model Context Protocol](https://modelcontextprotocol.io). Read tools surface your brand's scan results, recommendations, and content history. Write tools let an agent draft content, schedule replies, manage paid placements, and act on recommendations on your behalf.

The audience for this reference is developers integrating Citable into their own AI workflows. If you're a Citable user looking for product docs, start with the [introduction](/introduction) instead.

## Transports

Citable supports two transports.

| Transport           | Use it for                                                                                                                   |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **stdio**           | Local clients like Claude Desktop or Cursor running on your machine. Brand and user context come from environment variables. |
| **Streamable HTTP** | Hosted agents or remote integrations. Auth is an API key passed in the `Authorization: Bearer <key>` header.                 |

Both transports expose the same tool surface. See [authentication](/mcp/auth) for the full setup of each.

## Tool categories

The MCP server exposes three groups of tools.

**Read tools** return data — brand identity, AI visibility metrics, recommendation queue, posted content, attribution reports, prompt intelligence. All reads are scoped to the brand resolved from your auth context.

**Coarse write tools** (the `emit_*` family) bundle the most common write flows into single calls. Each `emit_*` call validates the action, performs the side effect, and records the result so it can be measured 30 days later. Prefer these for new integrations.

**Fine-grained write tools** expose individual steps — create a draft, schedule it, mark it posted, approve or dismiss a recommendation, ingest a conversation. These exist because the same actions are taken by humans in the Citable web app step-by-step, and the MCP surface mirrors that flow.

## Guarantees on every call

Every tool call goes through:

1. **Auth resolution.** Your brand and user are derived from the API key or environment context. Tools never accept `brand_id` as an input — it's always inferred.
2. **Cross-brand protection.** Write tools that take an ID resolve the target brand and reject if it doesn't match your auth context. You can only read and write your own brand's data.
3. **Action recording.** Every write tool records what happened, so the platform can measure the outcome later and your future recommendations get sharper.
4. **Rate limits.** Each brand has a per-hour rate limit, returned in standard `X-RateLimit-*` response headers.

## Versioning

The current namespace is `v1`. Within v1, the contract grows additively — new tools and new optional inputs are added; existing tools and required inputs don't change shape. You can code against v1 today and not worry about a breaking change for at least a quarter.

## Quick start

Once you have an API key from **Settings → API Keys** in the Citable web app:

```bash theme={null}
export CITABLE_MCP_URL="https://api.getcitable.com/mcp"
export CITABLE_API_KEY="..."
```

Or for stdio with Claude Desktop, add to your Claude Desktop config:

```json theme={null}
{
  "mcpServers": {
    "citable": {
      "command": "node",
      "args": ["/path/to/citable-mcp.js"],
      "env": {
        "CITABLE_BRAND_ID": "123",
        "CITABLE_USER_ID": "456"
      }
    }
  }
}
```

Verify the connection with the `ping` tool — it returns the resolved brand and user, so you can confirm you're talking to the right context before any real calls.

```
> ping()
< pong — citable-mcp v1, brand 123, user 456
```

You're connected. Browse the per-tool pages for what each tool does, the inputs it accepts, and the response shape.