企业官网建设流程全解析

如何用 spacetime mcp 把 SpacetimeDB 数据库暴露给 MCP 客户端

【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB

当你有一个正在运行的 SpacetimeDB 数据库，希望让支持 MCP 的 Agent 或编辑器（比如 Claude Desktop、Claude Code、Codex）直接操作它——列出数据库、读取 schema、执行 SQL、调用 reducer——而不用再走 shell 命令时，spacetime mcp就是这个桥梁。它在本地以 stdio 方式启动一个 MCP 服务，把客户端的请求转发到 SpacetimeDB 主机（或单个数据库），工具调用返回 JSON 结果。

本文适用的前提：数据库和主机已经存在，你本地装有spacetimeCLI。需要特别注意：文档明确标注 MCP 支持是不稳定功能（Unstable Feature），spacetime mcp命令可能存在破坏性变更，且某些已发布的 CLI 中可能还没有这个子命令，必要时需要从仓库源码构建（见 codex-plugin/README.md）。

准备条件：确认 CLI 里有 mcp 子命令

在配置任何客户端之前，先确认你的spacetimeCLI 包含该命令：

spacetime help mcp

根据 CLI Reference，spacetime mcp的用法是：

spacetime mcp [OPTIONS] [database]

可用选项只有两个：

• -s,--server <SERVER>— 指定承载数据库的服务器，取值可以是 nickname、host name 或 URL；
• --anonymous— 使用匿名身份执行，而不是你保存的登录身份。

关于身份：spacetime mcp默认使用你已保存的 SpacetimeDB 身份（即spacetime login登录后的身份），除非传入--anonymous。后续所有工具调用都以这个身份运行，权限边界见文末。

选择暴露范围：整个主机还是单个数据库

MCP 服务有两种形态，启动命令直接决定形态，也决定客户端工具调用的参数形状：

# 主机级（host-wide）：不指定数据库，服务整个 SpacetimeDB 主机 spacetime mcp --server local # 数据库级（database-scoped）：只服务 my-database 这一个库 spacetime mcp my-database --server local

my-database是文档中的示例值，替换为你自己的数据库名。两种形态的区别：

• 主机级：每个数据类工具都必须带database参数（值为数据库名或 identity），并且额外暴露list_databases工具；
• 数据库级：数据库在启动命令里已经固定，数据类工具不再需要database参数，list_databases也不可用。

除了位置参数，数据库名还可以来自环境变量SPACETIMEDB_DB_NAME：省略命令行参数时，服务会回退到该环境变量的值。

把服务暴露给 MCP 客户端

MCP 客户端通常通过 stdio 启动 MCP 服务器进程，所以核心就是让客户端去执行spacetime mcp。codex-plugin/README.md 给出了 Claude Desktop / Claude Code 这类客户端的配置形态（顶层mcpServers键）：

{ "mcpServers": { "spacetimedb": { "command": "spacetime", "args": ["mcp"] } } }

这对应主机级服务，代理在每次调用里指定数据库。如果要固定到单个数据库，把参数改成：

{ "mcpServers": { "spacetimedb": { "command": "spacetime", "args": ["mcp", "my-database"] } } }

或者保持args不变，在运行环境里设置SPACETIMEDB_DB_NAME环境变量。Codex 插件注册 MCP 服务器用的是同一条命令，无需额外配置，其形状为：

{ "spacetimedb": { "command": "spacetime", "args": ["mcp"] } }

如果你的客户端不经过 stdio 桥接，而是能直接发送 MCP JSON-RPC 请求，SpacetimeDB 主机本身就暴露了 HTTP 端点（可选路径，见 MCP Reference）：

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

POST /v1/mcp是主机级，每次数据工具调用都要带database参数；POST /v1/database/<name-or-identity>/mcp固定到单个数据库，数据工具调用省略database。认证使用与其他 SpacetimeDB HTTP API 调用相同的 bearer token，省略认证则使用匿名身份。

验证连接并调用工具

不要假设工具已经就绪：skills/mcp/SKILL.md 建议先读 MCP 客户端的工具列表（tools/list）再构造工具调用。这些工具是被动出现的，没有任何提示，连接成功后会以spacetimedb.list_databases、spacetimedb.get_schema、spacetimedb.sql、spacetimedb.call、spacetimedb.ping的形式出现。工具完全缺失则说明 MCP 服务器没有连上，此时应回退到spacetimeCLI。

工具全集（来自 MCP Reference）：

最简验证路径是调用ping，它会回显你传入的可选message，确认链路通畅。之后按 skills/mcp/SKILL.md 展示的巡检顺序操作（主机级示例，文档原样给出）：

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

注意list_databases只列出你自己拥有的数据库，匿名身份下结果为空；不知道数据库名时从它开始查。数据库级形态下同样的调用去掉database字段：

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

调用无参数的 reducer 时省略args或传空数组；带参数时按 reducer 参数顺序传值。需要等待持久化确认的读时，给sql传"confirmed": true。

身份与权限边界

这些规则在文档中明确列出，直接决定了你通过 MCP 能做什么：

1. Reducer 是正常写入路径。通过call修改应用状态，reducer 事务性地执行，要么整体提交、要么整体回滚。
2. sql工具可以读公共表；SQL 写入需要拥有该数据库。写入优先走 reducer，让授权与校验留在模块逻辑里。
3. 私有表不能通过 MCP SQL 读取。get_schema仍会显示私有表的声明，所以sql报no such table不一定是模块里没有这张表，也可能是当前身份读不到它。

常见错误与排查

MCP Reference 给出了四个典型报错的含义：

工具失败不会导致传输层断开，而是作为 MCP 响应体内的结果返回（结果带isError: true，错误信息以文本形式给出）。文档的建议是：在换工具形态或换database值重试之前，先读取错误文本。

限制

• MCP 支持目前是不稳定功能，参数和工具形态可能随版本发生破坏性变更；
• spacetime mcp在某些已发布 CLI 中可能还不存在，codex-plugin/README.md 的说明是：如果命令缺失，MCP 服务器无法启动，需要时可从本仓库构建 CLI；
• MCP 工具只能操作已经存在的数据库，不能替代 CLI 完成脚手架、编译模块、发布或生成 bindings 等步骤。

命令细节以 CLI Reference 的spacetime mcp一节和 MCP Reference 为准。

【免费下载链接】SpacetimeDBDevelopment at the speed of light项目地址: https://gitcode.com/GitHub_Trending/sp/SpacetimeDB