MCP Reference

SpacetimeDB can serve a host or a single database to MCP-aware agents and editors. The MCP server exposes tools for inspecting schemas, running SQL, and invoking reducers.

Unstable Feature

MCP support is currently unstable and subject to breaking changes.

Starting the MCP Server

Use the spacetime mcp command to bridge an MCP client over stdio to a SpacetimeDB host:

spacetime mcp --server local
spacetime mcp my-database --server local

When you omit the database argument, the MCP server is host-wide. When you pass a database name or identity, the MCP server is scoped to that database. The database argument can also come from the SPACETIMEDB_DB_NAME environment variable. When you run spacetime mcp from a project with a spacetime.json that names a single unambiguous server, the command uses that server unless you pass --server or --no-config. It does not infer a database from the config; omitting the database argument still starts a host-wide MCP server.

The command uses your saved SpacetimeDB identity unless you pass --anonymous.

HTTP Endpoints

SpacetimeDB also exposes MCP over HTTP for clients that can send MCP JSON-RPC requests directly:

POST /v1/mcp
POST /v1/database/<name-or-identity>/mcp

POST /v1/mcp is host-wide, so each data tool call includes a database argument. POST /v1/database/<name-or-identity>/mcp is scoped to one database, so data tool calls omit the database argument.

Use the same bearer token you would use for other SpacetimeDB HTTP API calls, or omit authorization to use an anonymous identity.

Host-wide vs Database-scoped Tools

The tool shape depends on whether the MCP server is host-wide or database-scoped. Read the MCP client's tool list before constructing tool calls.

In host-wide mode, every data tool takes a required database argument. The database value can be a database name or identity. Host-wide mode also exposes list_databases.

{ "database": "my-database", "sql": "SELECT * FROM message" }

In database-scoped mode, the database is fixed by the spacetime mcp <database> command. Data tools do not take a database argument, and list_databases is not exposed.

{ "sql": "SELECT * FROM message" }

Tools

Tool	Host-wide arguments	Database-scoped arguments	Description
list_databases	none	not available	Lists the databases owned by your identity on the host.
ping	optional message	optional message	Health check that echoes an optional message.
get_schema	database	none	Returns the schema as JSON, including types, tables, and reducers.
sql	database, sql, optional confirmed	sql, optional confirmed	Runs SQL and returns rows as JSON. Set confirmed to wait for a durably confirmed read.
call	database, reducer, optional args	reducer, optional args	Invokes a reducer. args is a JSON array of positional reducer arguments.

For reducer calls with no arguments, omit args or pass an empty array. For reducer calls with arguments, pass values in reducer parameter order:

{ "database": "my-database", "reducer": "send_message", "args": ["hello"] }

Identity and Permissions

MCP tools run with the identity used to start spacetime mcp, the same as other SpacetimeDB APIs.

Reducers are the normal write path. Use call to change application state through module logic. The reducer runs transactionally and either commits or rolls back.

The sql tool can read public tables. SQL writes require ownership of the database. Prefer reducers for writes so authorization and validation stay in the module.

Private tables are not client-readable through MCP SQL. The get_schema tool can still show private table declarations, so a no such table error from sql can mean the table is private for the current identity rather than absent from the module.

Common Errors

Error	Meaning
database argument must be a string	The server is host-wide and the tool call omitted database, or passed a non-string value.
unknown tool: list_databases	The server is database-scoped, so list_databases is not available.
`x` not found	No database named x exists on this server for the current identity, or the call used a name where an identity was required.
no such table: x	The table is private for the current identity, absent from the module, or the call targeted the wrong database.

Tool failures are returned in the MCP response body. Read the error text before retrying with a different tool shape or database value.