> For the complete documentation index, see [llms.txt](https://docs.graspil.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/en/mcp.md).

# MCP Server (AI agents)

Graspil provides its own **MCP server** — a way to connect an AI agent (Claude, ChatGPT, or any other [MCP](https://modelcontextprotocol.io/)-compatible client) directly to your data in Graspil, so the agent can build reports, look at your stats, and manage broadcasts and automations on its own — without opening the dashboard.

Once the MCP server is connected to your agent, you can just ask it in plain language:

> "Show me how many new users joined last week compared to the week before"\
> "Build a payment funnel report for June and save it"\
> "How much did I earn from the referral program this month?"\
> "Create a broadcast with this text ... and send it to all active users"

— and the agent will call the right tools, fetch the data, and answer.

{% hint style="info" %}
The MCP server is a thin layer on top of the regular Graspil API: the agent works with the same bots and permissions your API key allows, and access/plan restrictions apply exactly as they do through the dashboard or API.
{% endhint %}

***

## What the agent can do via MCP

| Area                                           | What the agent can do                                                                                                                                      | Plan             |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| [Reports](/en/api/reports.md)                  | List available events and resources (bots), build and preview reports (trends, funnels, retention, UTM), save finished reports, list previously saved ones | Premium          |
| Dashboards                                     | List, create, edit, and delete dashboards                                                                                                                  | Premium          |
| [Broadcasts](/en/api/broadcasts.md)            | Create, edit, launch, cancel, and list broadcasts                                                                                                          | Premium          |
| [Automations](/en/api/automations.md)          | Create, edit, publish/unpublish, delete, and list automations (trigger → action)                                                                           | Premium          |
| Landings                                       | Create, edit, delete, and list landing pages                                                                                                               | Premium          |
| Integrations                                   | List connected integrations and available integration types                                                                                                | Premium          |
| [Conversation history](/en/api/messages.md)    | View the bot's message history with users, with filters and text search (read-only)                                                                        | Premium          |
| [Referral program](/en/api/referral-system.md) | View balance, referral list, payout history, and effective rates (read-only)                                                                               | Premium          |
| Documentation                                  | Full-text search over Graspil's documentation — the agent can look up "how does this work" on its own                                                      | Any (incl. free) |

{% hint style="warning" %}
On the **free plan**, only documentation search is available via MCP. Every other area (reports, dashboards, broadcasts, automations, landings, integrations, conversation history, referral program) requires a **Premium** (or Trial) plan, otherwise the request fails with `403 Forbidden` ("Premium tariff required").
{% endhint %}

{% hint style="warning" %}
Sensitive referral-program operations (accruals, payouts, code ownership) are not exposed via MCP — those actions remain available only through the dashboard or the direct API.
{% endhint %}

***

## Authentication

The agent connects using your personal key from the [API Keys](https://app.graspil.com/api-keys) section — a plain single-bot key (from the "My Bots" section, see [Authorization](/en/api/auth.md)) doesn't work for MCP; you need a personal (user-level) key.

1. Open **Profile → API Keys** in the dashboard.
2. Click **"Create key"** and give it a name (e.g. "Claude MCP").
3. Optionally restrict the key to specific bots and per-section permissions (read-only / full access) — by default the key gives access to all your bots.
4. Copy the key value — it's shown once in plain text, so save it somewhere safe.

A single key works across every bot you have access to — the agent picks the right bot during the conversation (asking you if there's more than one), so there's no need to connect each bot separately.

***

## Connecting an agent

The Graspil MCP server speaks **Streamable HTTP** — most modern AI clients (Claude Desktop, Claude Code, etc.) support this as a "remote MCP server" configured by URL.

Server address: `https://mcp.graspil.com/mcp`

General configuration shape for clients that support remote MCP servers by URL with custom headers:

{% code overflow="wrap" %}

```json
{
  "mcpServers": {
    "graspil": {
      "url": "https://mcp.graspil.com/mcp",
      "headers": {
        "Api-Key": "YOUR_API_KEY"
      }
    }
  }
}
```

{% endcode %}

Exact steps vary by client:

* **Claude Desktop / Claude Code** — add the server under integration settings (Settings → Connectors / MCP servers), specifying the URL and the `Api-Key` header.
* **Other MCP-compatible clients** — use the equivalent mechanism for adding a remote MCP server by URL with a custom auth header.

Once connected, the agent will ask for the list of available bots (if there's more than one) and confirm which one to use for the conversation.

***

## FAQ

**Can the agent see other users' data?**\
No. The agent operates strictly within your API key's permissions — it only sees the bots and data your key can access.

**Can I restrict what the agent is allowed to do?**\
Yes. Just like a regular API key, you can restrict it to specific bots and grant "read-only" permissions per section (e.g. let the agent view reports but not create broadcasts) — configured when creating or editing the key in the "API Keys" section.

**What happens if I revoke the key?**\
The agent loses access immediately — the MCP server holds no data of its own and doesn't cache permissions for long; every request is checked against the same key.

**Do I need to install anything?**\
No, the server is already deployed and maintained by Graspil — you just need the API key and an MCP-compatible client.

**Why does the agent get `403 Forbidden`?**\
On the free plan, only documentation search is available via MCP — every other area (reports, dashboards, broadcasts, automations, landings, integrations, conversation history, referral program) requires a **Premium** (or Trial) plan; the request is rejected with `403` ("Premium tariff required"). Upgrade the account/bot to Premium.