> ## 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.

# The Sapot Agent Skill

> The companion skill that teaches a coding agent to drive the Sapot MCP correctly out of the box — scopes, boundaries, quota, recipes, and footguns.

The MCP tools are safe by construction, but an agent still drives them best when it understands the rules *before* it starts. The **Sapot Agent Skill** is a companion skill you install alongside the MCP connection so your agent gets the mental model up front — instead of learning it by hitting refusals.

It is a single skill file (`mcp-server/skill/SKILL.md`, skill name **`sapot-agent`**) that mirrors the tool catalog and teaches the agent how Sapot Chat governs it.

<Note>
  This is the **MCP skill** (`sapot-agent`) that teaches an agent to operate your account through the MCP server.
</Note>

## What it teaches

<CardGroup cols={2}>
  <Card title="Connection contract" icon="key">
    Auth is a scoped agent key sent as <code>Authorization: Bearer</code>, plus the <code>X-Sapot-Account-Id</code> header — the account is fixed by the connection, never a tool argument.
  </Card>

  <Card title="Default-deny scopes" icon="lock">
    A tool whose scope wasn't granted returns an auth error naming the missing scope. The skill teaches the agent that this is expected, not a bug to retry.
  </Card>

  <Card title="The two boundaries" icon="triangle-exclamation">
    Campaigns are draft-only and flow agents are intent-level. The skill frames both as enforced boundaries so the agent doesn't try to work around them.
  </Card>

  <Card title="429 = quota" icon="gauge">
    A <code>too\_many\_requests</code> / "Agent action quota exceeded" means the plan's MCP-action allowance is spent for the period — stop and tell the user.
  </Card>

  <Card title="Tools by scope" icon="list">
    A grouped index of all tools under each scope, so the agent picks the right tool for the capability it has.
  </Card>

  <Card title="Recipes + footguns" icon="book">
    End-to-end playbooks (triage, draft-a-blast, keep knowledge fresh, publish a flow, weekly readout) plus the sharp edges to avoid.
  </Card>
</CardGroup>

## When it triggers

The agent loads the skill whenever a request involves working with your Sapot Chat account through the MCP tools — triaging or replying to conversations, managing contacts, reading reports, curating AI Knowledge, managing WhatsApp templates, operating flow agents, or drafting campaigns/blasts. In short: any time the user asks it to touch the inbox, contacts, campaigns, knowledge, or flows.

## Install with Claude Code

<Steps>
  <Step title="Connect the MCP server">
    Register the Sapot Chat MCP server with your agent:

    ```bash theme={null}
    claude mcp add --transport http sapot https://mcp.sapot.ai/mcp --header "Authorization: Bearer YOUR_AGENT_KEY" --header "X-Sapot-Account-Id: YOUR_ACCOUNT_ID"
    ```

    Replace `https://mcp.sapot.ai/mcp` with your environment's MCP URL, `YOUR_AGENT_KEY` with your scoped key, and `YOUR_ACCOUNT_ID` with your numeric account id.
  </Step>

  <Step title="Place the skill alongside it">
    Copy `mcp-server/skill/SKILL.md` into your Claude Code skills directory (e.g. `~/.claude/skills/sapot-agent/SKILL.md`), or bundle it in a plugin. Keep the skill and the MCP connection together so both are present in the same session.
  </Step>

  <Step title="Confirm it loads">
    Start the agent and ask it to work with your account (for example, "list my open conversations"). With the skill installed it should reference scopes and boundaries in how it plans the work — not just fire tool calls blind.
  </Step>
</Steps>

<Tip>
  Grant the fewest scopes the task needs. The skill will tell the user which scope to add when a capability is missing, rather than looping on a refusal.
</Tip>

## What it changes

With the skill installed, the agent avoids the failure modes that a cold MCP client falls into:

| Without the skill                                           | With the skill                                                                                     |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Retries a scope refusal as if it were a transient error     | Recognises a default-deny refusal, stops, and names the scope to add                               |
| Assumes `draft_campaign` sends the blast                    | Prepares the draft, previews reach, and hands the **Send** click to a human                        |
| Passes label titles to audience tools (zero-reach audience) | Resolves numeric label ids via `list_labels` before `preview_campaign_audience` / `draft_campaign` |
| Sends ISO dates to report tools                             | Uses UNIX epoch **seconds** for `since` / `until` report windows                                   |
| Asks for or waits on raw flow-graph JSON                    | Operates flows at the intent level and points the user to the Flow Designer                        |
| Treats a `429` as a bug to hammer                           | Reads it as plan quota exhausted for the period and tells the user                                 |

The net effect is fewer wrong retries, correct draft-then-human-send behaviour, and reports that actually return data.

## Keep it in sync

<Warning>
  The skill mirrors the tool catalog in `mcp-server/app/tools.py`. As new scopes and tools ship, update the tools-by-scope list and recipes in `SKILL.md` so the agent keeps reaching for the right tool. Treat the skill as part of the tool surface, not as static docs.
</Warning>

## Related

<CardGroup cols={3}>
  <Card title="Overview" icon="robot" href="/ai-agents/introduction">
    What the AI-native MCP surface is and how it's kept safe.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/ai-agents/quickstart">
    Connect an agent and make a first tool call.
  </Card>

  <Card title="Authentication & Scopes" icon="key" href="/ai-agents/authentication">
    The default-deny scope model in detail.
  </Card>
</CardGroup>