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

# Quickstart

> Connect a coding agent to your Sapot Chat account and make your first tool call in a few minutes.

Go from zero to a first successful tool call in a few minutes.

## Prerequisites

* An **admin** login to your Sapot Chat account.
* **Claude Code** (or another MCP-compatible client).
* Your **numeric account id** — the number in your dashboard URL (`/app/accounts/<id>/…`), also shown in Settings.

<Steps>
  <Step title="Mint a scoped key">
    In the dashboard: **Settings → API & Agents → Create key**.

    * Give it a clear name (one key per agent or use case).
    * Grant the **fewest scopes you need** — for this Quickstart, just `conversations:read`.
    * Optionally set an expiry.

    <Warning>Copy the token now — the full value is shown only once. Afterwards you'll see only a masked preview.</Warning>
  </Step>

  <Step title="Connect">
    Register the Sapot Chat MCP server with your agent. With Claude Code:

    ```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 the key from step 1, and `YOUR_ACCOUNT_ID` with your numeric account id. The key and account id are fixed by the connection — you never pass the account into a tool call.

    <Note>
      **No hosted MCP URL yet?** The MCP server is a tiny stateless proxy — run it yourself and point it at the API. It holds no credentials and needs no model key:

      ```bash theme={null}
      cd mcp-server
      pip install -e .
      CHATWOOT_API_BASE_URL=https://chat.sapot.ai uvicorn app.server:app --host 127.0.0.1 --port 9000
      ```

      Then connect to your local instance (same key + headers):

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

      Your key still authenticates against the real API, so the agent operates your actual account — the local proxy just relays the request.
    </Note>
  </Step>

  <Step title="Verify">
    Ask your agent to list the available tools, then run a read:

    > "List my open conversations."

    which calls `list_conversations(status="open")`. A result confirms the connection is live and the key works. You'll only see tools your scopes unlock — with just `conversations:read`, that's the six read tools.
  </Step>
</Steps>

## Read the mental model before writing

Two things will otherwise look like bugs:

* A **`missing the required scope`** response means the key wasn't granted that capability — add the scope (or leave it off on purpose). See [Authentication & Scopes](/ai-agents/authentication).
* A **campaign that stays a draft**, or a **flow whose graph you can't see**, are enforced boundaries, not failures.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication & Scopes" icon="key" href="/ai-agents/authentication">
    The default-deny scope model and how keys authenticate.
  </Card>

  <Card title="The Agent Skill" icon="sparkles" href="/ai-agents/agent-skill">
    Install the companion skill so the agent uses the tools correctly out of the box.
  </Card>
</CardGroup>