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

# AI Agents & MCP

> Operate a Sapot Chat account with a coding agent (Claude Code or any MCP client) over a scoped, metered, IP-safe API.

<Note>
  The AI-native / MCP surface is verified on staging and rolling toward production. Endpoints and
  tool names are stable; treat the MCP server URL as environment-specific until GA.
</Note>

Sapot Chat lets you operate an account with a **coding agent** — [Claude Code](https://claude.com/claude-code), or any [MCP](https://modelcontextprotocol.io)-compatible client — over a **scoped, metered, IP-safe** API. The agent can triage and reply to conversations, manage contacts, pull reports, curate your AI Knowledge, manage WhatsApp templates, operate flow agents, and prepare campaign drafts.

Unlike handing an AI a full-access personal token, every agent key is limited to the exact capabilities you grant, is metered against your plan, and is prevented — server-side — from doing the two things that must stay human: **sending a blast** and **seeing how your AI flows are built**.

## Architecture at a glance

```
Coding agent (Claude Code / MCP client)
        │  Authorization: Bearer <agent key>
        │  X-Sapot-Account-Id: <account id>
        ▼
Sapot MCP server  ── stateless FastMCP proxy, holds no credentials,
        │            relays your token per-request
        ▼  api_access_token: <agent key>
Sapot REST API    ── validates the scoped agent token,
        │            enforces the default-deny scope allowlist
        ▼
Your account's data
```

The MCP server is a **thin pass-through**: it runs no AI/inference of its own and stores no credentials. Your agent holds the scoped key; the server relays it to the Sapot Chat API, which is the single point that authenticates and authorizes every call. You can also skip MCP and call the [REST API](/api-reference/introduction) directly with the same scoped token.

## The surface

**46 tools across 7 domains**, each unlocked by a capability scope:

| Domain             | Scope(s)                                    | What the agent can do                                              |
| ------------------ | ------------------------------------------- | ------------------------------------------------------------------ |
| Conversations      | `conversations:read`, `conversations:write` | list/search/filter/read; reply, assign, resolve, prioritise, label |
| Contacts           | `contacts:manage`                           | find/create/update/label contacts; resolve label ids               |
| Reports            | `reports:read`                              | KPI summaries, time series, live counts                            |
| AI Knowledge       | `knowledge:manage`                          | curate FAQs / products / promos + the business profile             |
| WhatsApp templates | `templates:manage`                          | list/create/update/delete/sync Meta templates                      |
| Flow agents        | `flows:manage`, `flows:publish`             | operate & publish flow agents (intent-level only)                  |
| Campaigns          | `campaigns:draft`                           | prepare campaign drafts + preview audience                         |

## Safe by construction

<CardGroup cols={2}>
  <Card title="Default-deny scopes" icon="lock">
    A key reaches only the endpoints its scopes allow; everything else is refused.
  </Card>

  <Card title="Flows are intent-level" icon="diagram-project">
    The Flow Designer graph is never exposed to an agent — design stays private.
  </Card>

  <Card title="Campaigns are draft-only" icon="paper-plane">
    An agent prepares a blast; a human clicks <b>Send</b> in the dashboard.
  </Card>

  <Card title="Metered per plan" icon="gauge">
    Every successful call counts against your plan's allowance; over it returns <code>429</code>.
  </Card>
</CardGroup>

## Get started

<CardGroup cols={3}>
  <Card title="Quickstart" icon="rocket" href="/ai-agents/quickstart">
    Zero to a first tool call in a few minutes.
  </Card>

  <Card title="Authentication & Scopes" icon="key" href="/ai-agents/authentication">
    How agent keys authenticate and the default-deny scope model.
  </Card>

  <Card title="The Agent Skill" icon="sparkles" href="/ai-agents/agent-skill">
    A companion skill so the agent drives the tools correctly.
  </Card>
</CardGroup>

## Who this is for

External customers and partners wiring a coding agent to **their own** Sapot Chat account. If you just want to use the feature without code, the in-app Help Center has a no-code walkthrough; these docs are the technical reference.