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

Task	Use
List databases, read a schema, run SQL, call a reducer	MCP tools
init, build, publish, generate, start, logs	spacetime CLI (see the cli skill)

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

Tool	Arguments	Returns
list_databases	none	the databases you own, with identity and names
get_schema	database	tables and reducers as JSON
sql	database, sql, optional confirmed	rows as JSON
call	database, reducer, optional args (JSON array)	the reducer outcome
ping	optional message	a health check

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" } }

When spacetime mcp runs inside a project with a spacetime.json that has a single unambiguous server, it uses that server unless --server or --no-config is passed. It does not infer a database from the config; omitting the database argument still means host-wide mode.

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

Message	Meaning
database argument must be a string	The server is host-wide and you omitted database
unknown tool: list_databases	The server is scoped to one database already
`x` not found	No such database on this server, or a name where an identity was meant
no such table: x	The table is private, or you are querying the wrong database
No spacetimedb tools at all	No MCP server is connected. Use the CLI instead (cli skill)

spacetime mcp is UNSTABLE and subject to breaking changes. If a client cannot start it, fall back to the CLI commands in the cli skill.

Reference: https://spacetimedb.com/docs