MCP server reference

Every Spatibase project has an MCP (Model Context Protocol) server, so AI assistants and your own agents can read the project and, when allowed, change it. This reference is for developers: the URL and transport, what each credential unlocks, how to connect, every tool, dry runs, limits and security notes. For a step-by-step setup in Claude, ChatGPT or Cursor, see Connect an AI assistant.

On this page, $PROJECT_ID is the project’s UUID (the id in the project’s web address), and $EDIT_KEY is an AI assistant key (sb_edit_…) created by a project owner.

URL and transport

Each project has its own MCP endpoint:

https://mcp.spatibase.com/projects/$PROJECT_ID

Copy the exact address from the project’s AI agents page, in Connect your assistant (This project’s assistant address). That value is the source of truth.

The server uses the Streamable HTTP transport and is stateless:

• Every request is a POST with one JSON-RPC message (or a batch) and its own Authorization header.
• Responses are plain JSON. There is no SSE stream and no Mcp-Session-Id. A GET answers 405.
• The server does not remember initialize between requests.

Which credential gives which access?

What a client can do follows only from its credential, sent as Authorization: Bearer <credential>. Keys in the query string or in an X-API-Key header are ignored on this endpoint. The tool list a client receives contains only the tools its credential allows; calling any other tool fails with MCP error -32602: Tool … not found.

What a person’s role allows over OAuth:

Writing always needs a credential: a public project is only public to read. Only owners create edit keys, in the web app (API, Access & keys, Create key, For an AI assistant). Editors and developers connect their assistants through OAuth instead.

Connect a client

Claude Code

claude mcp add --transport http spatibase "https://mcp.spatibase.com/projects/$PROJECT_ID" \
  --header "Authorization: Bearer $EDIT_KEY"

Leave out --header to read a public project, or to sign in with OAuth: run /mcp in Claude Code, choose spatibase and sign in.

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "spatibase": {
      "url": "https://mcp.spatibase.com/projects/PROJECT_ID",
      "headers": { "Authorization": "Bearer EDIT_KEY" }
    }
  }
}

Claude Desktop with a key

Claude Desktop’s configuration file starts local servers, so bridge to the remote server with mcp-remote (needs Node.js):

{
  "mcpServers": {
    "spatibase": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.spatibase.com/projects/PROJECT_ID",
               "--header", "Authorization: Bearer ${SPATIBASE_KEY}"],
      "env": { "SPATIBASE_KEY": "EDIT_KEY" }
    }
  }
}

Claude.ai, ChatGPT and Claude Desktop custom connectors use the URL and OAuth; no key is pasted.

Your own agent

With the MCP TypeScript SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js'
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'

const url = new URL(`https://mcp.spatibase.com/projects/${process.env.PROJECT_ID}`)
const transport = new StreamableHTTPClientTransport(url, {
  requestInit: { headers: { Authorization: `Bearer ${process.env.SPATIBASE_KEY}` } }
})
const client = new Client({ name: 'my-agent', version: '1.0.0' })
await client.connect(transport)

const result = await client.callTool({ name: 'search_entries', arguments: { type: 'store', limit: 5 } })
console.log(result.structuredContent)

curl

One request carries one message. The Accept header may be just application/json.

curl -s -X POST "https://mcp.spatibase.com/projects/$PROJECT_ID" \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer $EDIT_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"count_entries","arguments":{"type":"store"}}}'

Tools

Results are compact JSON, returned both as text and as structuredContent. Ids and apiKeys are always included so calls can be chained. Geometry is summarised as {type, centroid, bbox, vertices} (a point keeps its coordinates) unless you pass includeGeometry: true.

Prompts: summarize_project, and find_missing_field (arguments type and field).

No credential can manage API keys, switch a project between public and private, manage members or the webhook, duplicate or delete the project or empty the trash.

Translations

In a project with languages the tools know about them:

• The read tools (search_entries, get_entry, get_group, get_entries_geojson) take locale, like the Content Delivery API: locale: "de" returns German with a fallback to the default language and missingTranslations, and locale: "*" returns all stored translations.
• create_entry, update_entry and bulk_update_entries take translations, for example {"de": {"title": "Wald", "values": {"description": "…"}}}. It is merged: only the languages and fields you send change, null removes one. Only the title and text and rich text fields can be translated, and only in the project’s non-default languages; other requests are refused with the reason.
• search_drafts takes missingLocale.
• import_features takes locale with matchBy, and reads language columns such as title_de.
• update_project_settings takes locales and needs the model tier (and confirm: true).

The workflow the tool descriptions teach: find the entries with missingLocale, read each draft, write translations as drafts, and leave publishing to a person. Translated drafts are marked as changed by an assistant, like every other draft change.

Dry runs and errors

Every tool that takes dryRun defaults to dryRun: true: bulk_update_entries, import_features, import_dataset, mark_ready, publish_project, unpublish_entries, restore_version, delete_entries and delete_assets. The first call shows what would happen; nothing is written until the client calls again with dryRun: false. Model tools work the same way with confirm.

Tool errors come back as tool results with isError: true and the API’s plain message:

{ "error": "This entry changed since you loaded it…", "status": 409, "code": "entry_changed" }

What editors see

Every change appears in the project’s Activity, as “AI assistant (key name)” for an edit key or “person via app” for an OAuth connection. Drafts an assistant changed are flagged in Entries (the Changed by AI switch in the Status filter) until someone edits them or publishes them. The publish_project preview counts them too. Activity has an AI changes checkbox for the change log.

The client name comes from clientInfo.name in an initialize request, otherwise from the first word of the User-Agent header, or from the OAuth client’s registered name.

Limits

A wrong, revoked, expired or other project’s key gets 401 with error="invalid_token". An expired temporary project token gets 401 with the code token_expired, one the owner removed in Members gets 401 with token_revoked (the agent should stop and ask, not start a new project), and a temporary project that expired gets 410 with project_expired (for 30 days after it was deleted). Expired or revoked credentials do not count towards the failed-credential limit. See Limits for the limits of the other APIs.

Security notes

• Prompt injection. Tool results are the project’s data. An entry’s text can contain instructions aimed at an assistant; every tool description warns the model about this. Give an assistant the smallest credential that does the job, keep publishing and deleting off unless needed, and review the entries flagged Changed by AI.
• Keys are secrets. An edit key can change drafts. Keep it out of code repositories and web pages, and revoke it when the assistant no longer needs access.
• Browser requests. A request that carries an Origin header from a website other than the Spatibase web app is refused with 403.
• Logging. Spatibase logs the tool, the key prefix or connection id, the duration and the size of each call, never a credential or content.

Related

• OAuth for MCP clients
• Connect an AI assistant
• What assistants can do
• Authentication
• Content Delivery API reference