GoPie
Get started
Menu
On this page

API & MCP

MCP server overview

GoPie ships a Model Context Protocol (MCP) server, so AI clients — Claude, Cursor, and anything else that speaks MCP — can browse your projects, inspect schemas, and run read-only SQL against your data through a standard interface. Instead of copying results into a chat, the assistant queries GoPie live.

What you get

Connect a client and it gains 9 tools (list projects, inspect a dataset, run SQL, create a dataset from a file, and more) and 3 resources (browsable projects, datasets and schemas). The server also injects live guidance — your organisation context and SQL tips — so the assistant writes queries that actually run the first time.

The endpoint

MCP is served over streamable HTTP at:

https://<your-gopie-host>/mcp

On a local self-hosted stack that's http://localhost:8002/mcp. It's stateless — no session handshake to manage — and every request authenticates with a bearer API key, exactly like the REST API.

Important

MCP requires an organisation-wide key (prefix gp_mcp_). Application-scoped gp_pub_ keys are refused with a 403 — an assistant that can write arbitrary SQL shouldn't be boxed into one application's grants, so MCP only accepts keys that carry full organisation access. Getting one is the next section.

Get an organisation-wide key

This is the one rough edge today. Application keys have a tidy UI; organisation-wide MCP keys don't have a create button yet. Until one ships, an organisation owner or admin can mint a key directly against the auth service while signed in to GoPie.

Mint an organisation-wide key (advanced)

While signed in to your GoPie web app as an owner or admin, call the auth service's key-creation endpoint with your session cookie. The configId: "mcp" is what produces an organisation-wide gp_mcp_ key (rather than an application-scoped one):

curl -X POST "https://<your-gopie-app>/api/auth/api-key/create" \
  -H "Content-Type: application/json" \
  -H "Origin: https://<your-gopie-app>" \
  -b "better-auth.session_token=<your-session-cookie>" \
  -d '{"configId": "mcp", "name": "My MCP key", "organizationId": "<org-id>"}'

The response returns the plaintext key once, starting with gp_mcp_ — copy it immediately; only a hash is stored. Keep it secret: an organisation-wide key can read every dataset in the org.

Once you have the key, head to MCP setup to wire it into your client.

A local alternative: the stdio binary

There's also a standalone gopie-mcp binary that speaks MCP over stdio for local, single-user setups. It doesn't use API keys at all — it connects directly to your datastores with credentials in its environment. That makes it convenient for a self-hoster on their own machine and unsuitable for anything shared. It's covered alongside the HTTP setup on the next page.

What MCP can and can't do

  • Read-only SQL — the same SELECT / WITH / DESCRIBE / SUMMARIZE allowlist as the REST API, capped at 1,024 rows and a 30-second timeout per query.
  • Create datasets — the create_dataset and get_upload_url tools can ingest a file from a URL, a genuine write path (see the tools reference).
  • Not chat, dashboards, or reports — those richer flows are the REST API's job. MCP is the discovery-and-query surface.
Give feedback