GoPie
Get started
Menu
On this page

API & MCP

Connect an MCP client

Once you have an organisation-wide gp_mcp_ key, connecting a client is a few lines of config. Every client points at the same endpoint — https://<your-gopie-host>/mcp — and sends your key as a bearer token. Pick your client below.

Note

GoPie's MCP server uses streamable HTTP. Modern clients (Claude, Cursor) speak it natively. Older SSE-only MCP clients that expect a long-lived server-to-client event stream won't connect — use a streamable-HTTP client, or the stdio binary locally.

Claude Code

Add the server from the terminal:

claude mcp add --transport http gopie https://<your-gopie-host>/mcp \
  --header "Authorization: Bearer gp_mcp_your_org_wide_key"

Then ask Claude about your data — "what datasets are in my Sales project?" — and it'll use the GoPie tools. Manage it later with claude mcp list and claude mcp remove gopie.

Cursor

Add GoPie to your mcp.json (.cursor/mcp.json in a project, or the global one):

{
  "mcpServers": {
    "gopie": {
      "url": "https://<your-gopie-host>/mcp",
      "headers": { "Authorization": "Bearer gp_mcp_your_org_wide_key" }
    }
  }
}

Cursor picks it up on reload; the GoPie tools become available to the agent.

Claude Desktop

Claude Desktop connects to a hosted GoPie two ways:

Remote connector

Add GoPie as a custom connector pointing at https://<your-gopie-host>/mcp with an Authorization: Bearer gp_mcp_… header. This needs a publicly reachable HTTPS endpoint (the streamable-HTTP connector, not the SSE one).

Local stdio binary

If you're running GoPie locally, use the stdio binary below — no API key, but it needs datastore credentials in its config.

Any streamable-HTTP client

For a client not listed here, the contract is:

  • URL: https://<your-gopie-host>/mcp
  • Method: POST JSON-RPC (no Mcp-Session-Id — the server is stateless)
  • Headers: Authorization: Bearer gp_mcp_…, Content-Type: application/json, Accept: application/json, text/event-stream

A missing key returns 401; an application-scoped key returns 403 — MCP needs an organisation-wide key.

Local stdio binary

For a single developer running GoPie on their own machine, the standalone gopie-mcp binary is often simplest — it speaks MCP over stdio and needs no API key. Build it from the server source:

go build -o gopie-mcp ./cmd/mcp

Then point your client's config at it. A Claude Desktop entry:

{
  "mcpServers": {
    "gopie": {
      "command": "/path/to/gopie-mcp",
      "args": ["stdio"],
      "env": {
        "GOPIE_MCP_ORG_ID": "<org-id>",
        "GOPIE_POSTGRES_HOST": "localhost",
        "GOPIE_POSTGRES_PORT": "5432",
        "GOPIE_POSTGRES_DB": "gopie",
        "GOPIE_POSTGRES_USER": "postgres",
        "GOPIE_POSTGRES_PASSWORD": "postgres",
        "GOPIE_S3_ENDPOINT": "http://localhost:9000",
        "GOPIE_S3_ACCESS_KEY": "minioadmin",
        "GOPIE_S3_SECRET_KEY": "minioadmin"
      }
    }
  }
}
Warning

The stdio binary connects directly to your Postgres and object storage — there is no API-key auth layer, and organisation scoping comes only from GOPIE_MCP_ORG_ID. It's for local, single-user use. For anything shared or remote, use the HTTP endpoint with an organisation-wide key.

The binary accepts flags to tune limits — --query-timeout (default 30s), --max-rows (default 10, capped at 1,024), and --org-id. The full tool set is identical to the HTTP server.

Verify the connection

Whichever client you used, ask it to list your projects. If it comes back with your real project names, the tools are wired up. If it reports an auth error, re-check that your key starts with gp_mcp_ (not gp_pub_) — that's the most common cause.

Give feedback