MCP

SpacetimeDB over MCP

A SpacetimeDB host speaks MCP, so an MCP-aware client can operate a live database with tool calls instead of shell commands. If the client exposes spacetimedb tools, use them for anything that reads or changes a running database.

Check the tool list before deciding they are missing. The tools are passive: they appear as spacetimedb.list_databases, spacetimedb.get_schema, spacetimedb.sql, spacetimedb.call, and spacetimedb.ping, and nothing announces them.

Which to reach for

The MCP tools only operate a database that already exists. They cannot scaffold a project, compile a module, publish, or generate bindings, so the two are complementary rather than alternatives. Prefer the tools when they are present: they are typed, they return JSON, and the client can gate the destructive ones. When no MCP client is attached, the equivalent CLI commands are correct.

The tools

list_databases lists only your own databases, so it is empty for an anonymous identity. Start there when you do not know the database name.

Two shapes, so read tools/list first

A server is either host-wide or scoped to one database. Do not assume which:

Host-wide (spacetime mcp with no database, or POST /v1/mcp). Every data tool takes a required database argument, a name or an identity, and list_databases is offered:

{ "name": "sql", "arguments": { "database": "mydb", "sql": "SELECT * FROM message" } }

Scoped (spacetime mcp <database>, or POST /v1/database/<db>/mcp). The connection fixes the database, so there is no database argument and no list_databases:

{ "name": "sql", "arguments": { "sql": "SELECT * FROM message" } }

Rules that do not change

The tools run with your identity, exactly as the HTTP API does. The model is the same as everywhere else, so the concepts skill still governs:

1. Reducers are the write path. Use call to change data. It runs in a transaction that either fully commits or fully rolls back.
2. SQL writes require ownership. sql reads public tables; writing through it needs you to own the database. Prefer call.
3. Private tables are not client-readable. get_schema still shows a private table's declaration, so a no such table error from sql usually means the table is private rather than missing. Access depends on your identity, so do not assume a private table is readable.
4. Tool errors come back in band. A failed reducer or a bad query returns a result with isError: true and the message as text, not a transport failure. Read the text before retrying.

Inspecting a database

list_databases {}
get_schema     { "database": "mydb" }
sql            { "database": "mydb", "sql": "SELECT * FROM message" }
call           { "database": "mydb", "reducer": "send_message", "args": ["hello"] }

Pass "confirmed": true to sql to wait for a durably confirmed read.

Troubleshooting

spacetime mcp is UNSTABLE and may not be in a released CLI yet, so a client that cannot start it falls back to the CLI commands in the cli skill.

Reference: https://spacetimedb.com/docs