---
title: "连接 SurrealDB 托管 MCP"
summary: "托管服务地址为 https://mcp.surrealdb.com，通过 OAuth 登录。无头环境使用 SURREALDB_TOKEN，本地服务独立配置。"
category: mcp
level: starter
surfaces: [cli, app, ide]
tags: ["MCP", "SurrealDB", "plugins", "OAuth"]
canonical: /tips/surrealdb-codex-mcp/
---

# 连接 SurrealDB 托管 MCP

托管服务地址为 https://mcp.surrealdb.com，通过 OAuth 登录。无头环境使用 SURREALDB_TOKEN，本地服务独立配置。

SurrealDB 文档包含 Codex 配置说明，写在 `surrealdb.com/docs/agents/codex`。托管入口是 `https://mcp.surrealdb.com`，就在主机根上，**不要**再拼 `/mcp` 或 `/sse`。拼了会 404。它和 `https://api.surrealdb.com/api/mcp` 是同一挂载，**不要**两张表都加。

只要 Cloud MCP：

```bash
codex mcp add surrealdb --url https://mcp.surrealdb.com
codex mcp login surrealdb
```

```toml
[mcp_servers.surrealdb]
url = "https://mcp.surrealdb.com"
enabled = true
```

会话里批准 OAuth。托管页 TOML 还写过 `auth = "oauth"`，`mcp add` 之后用 `mcp login` 即可，不要再抄 Claude 的 `--transport http`。无头 / CI 才用个人访问令牌。官方 Codex 页的变量名是 `SURREALDB_TOKEN`，必须在**启动 Codex 的进程**里：

```toml
[mcp_servers.surrealdb]
url = "https://mcp.surrealdb.com"
bearer_token_env_var = "SURREALDB_TOKEN"
enabled = true
```

OAuth 与 Bearer token 请选择一种认证方式。令牌那张不要再 `mcp login`。通过环境变量提供 token。

要技能和 MCP 打在一起，才走官方插件仓。清单 `.agents/plugins/marketplace.json` 的 name 是 surrealdb，插件 name 是 surrealdb，所以是 `surrealdb@surrealdb`：

```bash
codex plugin marketplace add surrealdb/ai-codex-plugin --ref main
codex plugin add surrealdb@surrealdb
```

装完策略是 `ON_INSTALL`，应弹出 Surreal ID 登录。仓里还有 `agent-memory@surrealdb`（同一托管 URL）和 `surrealdb-local@surrealdb`（自建）。`surrealdb` 和 `agent-memory` 会把同一套托管工具登记成两台，不需要就只装一个。Agent Memory / Spectron 旧文还写 `spectron@surrealdb` 和本地 clone 再 `marketplace add "$PWD"`，现行清单**没有** spectron，不要抄。

插件已经登记 `surrealdb` 时，不要再手写一张同 URL 的 `[mcp_servers.surrealdb]`。官方 `npx skills add surrealdb/agent-skills` 只装技能，**不会**登记 MCP，也未指定 `--agent codex`，不要把它当插件安装器，也不要和插件技能叠两份。

自建 / 本机实例才带 `/mcp`。默认示例：

```bash
export SURREALDB_MCP_URL="http://127.0.0.1:8000/mcp"
export SURREALDB_MCP_TOKEN="your-session-jwt"
codex mcp add surrealdb-local --url http://127.0.0.1:8000/mcp --bearer-token-env-var SURREALDB_MCP_TOKEN
```

本机 404 先看实例有没有 `--deny-http mcp`。`surreal-bearer-` 开头的 grant key **不是** HTTP 访问令牌，要先换成 JWT。不要用 `surreal mcp` stdio 去接正在跑的那台库：stdio 会另起嵌入式 datastore。不要把本机 `/mcp` 和托管根 URL 写成同一张表。

能改 schema 和数据，保持工具批准。网页 Cloud 不读取你这台 `CODEX_HOME`。配置后重新打开会话。用 `codex mcp get surrealdb` 看传输是 streamable_http，url 是 `https://mcp.surrealdb.com`。

## 来源

- [SurrealDB · Codex](https://surrealdb.com/docs/agents/codex)
- [surrealdb/ai-codex-plugin](https://github.com/surrealdb/ai-codex-plugin)
- [SurrealDB · MCP endpoint](https://mcp.surrealdb.com/)