MCP Server

Quick Start

SparkAI comes with a built-in MCP server. Connect it once and you can ask Claude about your tickets, chats and traffic in plain English, no dashboard needed.

Nothing is turned on for writing at this point. A brand new key can read, and that is all. See Writes are locked by default.

Connect It

The server speaks streamable HTTP at:

If your client only supports Server-Sent Events, use the fallback:

A key is required

Unlike some of the other Spark apps, there is no anonymous mode here. Every request must carry Authorization: Bearer <your key>, and a token the server does not recognise gets a flat 401. There is no guest session to fall back to.

MCP keys look like spark_mcp-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6. You create them in the dashboard, they are shown once, and they come in two scopes:

Your app's REST API key (spark_ai-...) is not accepted by the MCP server. The two key types are separate on purpose, so a key that can chat cannot also work your desk. Use a spark_mcp- key here.

Claude Desktop config

Claude Desktop reaches remote servers through mcp-remote. Add this to your config file and swap in your own key:

{
  "mcpServers": {
    "spark-ai": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sparkbrain.app/api/mcp/mcp",
        "--header",
        "Authorization: Bearer spark_mcp-YOUR_KEY_HERE"
      ]
    }
  }
}

Restart Claude Desktop afterwards. If the connector does not appear, the usual causes are a typo in the key, a key that has expired, or an IP allowlist on your app that does not include the machine you are on.

Just Ask

You do not need to know any tool names. Ask the way you would ask a colleague:

• "What tickets are open right now?"
• "Summarise this week's conversations."
• "Reply to ticket 412 telling them it's fixed."
• "Who's waiting in live chat?"
• "Add an FAQ about refunds."

Claude picks the right tool for you. The last two are writes, so they will ask you to approve before anything actually changes.

What It Can Reach

Twenty three tools in total: eighteen that only read, and five that can change something. Everything is scoped to your own app, so a key can never see another customer's data.

Reading

Writing

There are two more tools, plan_app_kit and create_app_kit, that register brand new apps. Those are reserved for the account operator key and are not reachable with a per-app spark_mcp- key.

Writes Are Locked By Default

A fresh key cannot change anything. Two separate gates stand in front of every write, and both have to open.

Gate one: your dashboard switches

Each write tool has its own switch on your app, and every one of them starts off. Turn on only what you want:

Without the switch, the tool returns write_access_disabled and nothing happens. Note that add_faq shares the config switch, since both are config writes.

Gate two: your click

Even with the switch on, every single write asks you first. Claude pops a confirm dialog naming exactly what is about to happen, including the ticket number or the text being sent, and the write only runs if you approve it. The model cannot tick that box for you.

It fails closed too. Decline it, ignore it, or let it time out and nothing is written. If the dialog itself errors, the write is refused rather than quietly allowed.

Two extra safeguards. A read scope key can never write, whatever your switches say. And rotate_mcp_key is deliberately two step: the first call only hands back an impact report, and you have to call it again with a confirmation phrase before a key actually moves.

Keeping Keys Safe

Your keys are stored as a hash, never in plain text, so nobody can read one back out of the database, us included. That is also why the full key is shown only once at creation. Lose it and you make a new one.

Every key also tracks when it was last used and how many calls it has made, so you can spot one you have forgotten about. If a key ever leaks, rotate or revoke it and you are done.