Graspil MCP

For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

MCP Server (AI agents)

Graspil provides its own MCP server — a way to connect an AI agent (Claude, ChatGPT, or any other MCP-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	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	Create, edit, launch, cancel, and list broadcasts	Premium
Automations	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	View the bot's message history with users, with filters and text search (read-only)	Premium
Referral program	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 section — a plain single-bot key (from the "My Bots" section, see Authorization) 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" %}

{
  "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.