Xata MCP server

MCP 服务器

将 Cursor、Claude、VS Code 及其他 MCP 客户端连接到 Xata

Xata MCP 服务器让 AI 助手和智能体能够通过模型上下文协议（MCP）与你的 Xata 组织、项目和分支进行交互。

什么是 Xata MCP 服务器？

• 一个与 Xata API 一同运行的托管 MCP 服务器——无需在本地安装或运行任何内容。
• 通过浏览器中的 OAuth 进行身份验证，或在无头环境中使用 Xata API 密钥进行身份验证。
• 可从任何支持通过 Streamable HTTP 连接远程服务器的 MCP 客户端访问。

服务器 URL：

https://api.xata.tech/mcp

该服务器使用 Streamable HTTP 传输方式。没有 SSE 端点，也没有本地（npm）版本的服务器。

身份验证

MCP 服务器支持两种身份验证方法：

方法	适用场景	客户端要求
OAuth	在编辑器/聊天中进行交互式使用	支持 MCP OAuth（动态客户端注册）
API 密钥	自动化、CI、无头智能体	支持自定义 HTTP 标头

OAuth

对于支持 OAuth 的客户端，你只需要提供服务器 URL。当客户端首次连接时，它会向 Xata 注册自身、打开浏览器窗口，并要求你登录 Xata 账户并批准访问。令牌有效期较短，且作用域仅限于 MCP 服务器。

API 密钥

支持自定义标头的客户端可以使用 Xata API 密钥进行身份验证：

Authorization: Bearer YOUR_XATA_API_KEY

[!WARNING]

请为 MCP 访问创建专用的 API 密钥，而不要复用现有密钥。将其存储在环境变量或客户端的密钥存储中——切勿将其提交到源代码管理中。

设置你的 MCP 客户端

Cursor

[!TIP]

Cursor 提供深链接，可快速完成 OAuth 设置：

添加到 Cursor

或者，你也可以手动添加：

1. 打开命令面板并搜索“Cursor Settings”。
2. 在 Tools & MCP 下，点击 New MCP Server。
3. 将 Xata 服务器添加到打开的配置文件中：

{
  "mcpServers": {
    "xata": {
      "url": "https://api.xata.tech/mcp"
    }
  }
}

4. 保存文件。Cursor 会提示你进行身份验证——按照浏览器流程操作并批准访问你的 Xata 账户。

Claude Code

从终端添加服务器：

claude mcp add --transport http xata https://api.xata.tech/mcp

然后启动 Claude Code 并运行 /mcp 斜杠命令。选择 xata 服务器，并按照浏览器中的说明进行身份验证。

如需使用 API 密钥代替 OAuth（例如在 CI 中）：

claude mcp add --transport http xata https://api.xata.tech/mcp \
  --header "Authorization: Bearer YOUR_XATA_API_KEY"

VS Code

VS Code 中的 MCP 服务器需要 GitHub Copilot 和 GitHub Copilot Chat 扩展。

1. 打开命令面板（Cmd+Shift+P / Ctrl+Shift+P）。
2. 运行 MCP: Add Server 并选择 HTTP。
3. 输入 https://api.xata.tech/mcp 作为 URL，输入 xata 作为名称。

或者，手动将其添加到配置中：

{
  "servers": {
    "xata": {
      "type": "http",
      "url": "https://api.xata.tech/mcp"
    }
  }
}

从 MCP: List Servers 启动服务器，并在提示时允许其进行身份验证。

Claude（网页版和桌面版）

[!TIP]

打开 Claude 的自定义连接器对话框，其中已预填 Xata 的详细信息：

将 Xata 连接到 Claude

在 Claude 中查看并确认连接器，然后使用 Xata 进行身份验证。

或者，手动将 Xata 添加为自定义连接器：

1. 转到 Settings → Connectors。
2. 点击 Add custom connector。
3. 输入 https://api.xata.tech/mcp 作为服务器 URL，然后点击 Add。
4. 按照提示使用你的 Xata 账户登录。

[!NOTE]

使用远程 MCP 的自定义连接器并非在所有 Claude 套餐中都可用，在团队套餐中可能需要组织所有者才能添加。详情请参阅 Claude 文档。

ChatGPT

使用自定义连接器将 ChatGPT 连接到 Xata：

1. 在 ChatGPT 中，转到 Settings → Connectors → Advanced settings 并启用 Developer mode。
2. 在 Connectors 选项卡中，使用以下服务器 URL 创建新连接器：

https://api.xata.tech/mcp

3. 选择 OAuth 作为身份验证方式，并在提示时完成授权流程。
4. 在每个你想使用 Xata 的聊天中，点击 + 按钮并在 Add sources 下启用 Xata 连接器。

Codex CLI

添加 Xata 服务器：

codex mcp add xata --url https://api.xata.tech/mcp

[!NOTE]

add 命令可能会打开浏览器并报告 OAuth 错误。如果发生这种情况，请继续执行下面的登录命令；xata 服务器条目已经保存。

使用显式 OAuth 作用域向 Xata 进行身份验证：

codex mcp login xata --scopes mcp-client,offline_access

在浏览器中完成授权。offline_access 作用域允许 Codex 刷新其 Xata 会话，而无需再次进行浏览器授权。

然后启动 codex，运行 /mcp，并验证 xata 已连接并完成身份验证。

Antigravity CLI

将 Xata 添加到你的全局 MCP 配置中：

{
  "mcpServers": {
    "xata": {
      "serverUrl": "https://api.xata.tech/mcp"
    }
  }
}

如需仅为单个项目启用 Xata，请改为在该项目的根目录中使用 .agents/mcp_config.json。

启动 agy 并输入 /mcp。在 MCP Manager 中，为 xata 使用 Authenticate，并按照提示完成 OAuth。

OpenCode

将 Xata 服务器添加到你的 OpenCode 配置文件中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xata": {
      "type": "remote",
      "url": "https://api.xata.tech/mcp"
    }
  }
}

然后从终端进行身份验证：

opencode mcp auth xata

Amp

从终端添加服务器：

amp mcp add xata https://api.xata.tech/mcp

然后启动 amp——系统应会提示你在浏览器中进行身份验证。运行 /mcp list tools 以确认服务器已连接。

Windsurf

1. 在 Windsurf 中，打开 Cascade 面板并点击 MCP（锤子）图标，然后点击 Configure 打开原始配置文件（~/.codeium/windsurf/mcp_config.json）。
2. 添加 Xata 服务器条目：

{
  "mcpServers": {
    "xata": {
      "serverUrl": "https://api.xata.tech/mcp"
    }
  }
}

3. 保存文件，并在 Cascade 侧边栏中点击 Refresh。在浏览器窗口打开时完成 OAuth 流程。

Zed

1. 打开 Settings → AI → MCP Servers 并点击 Add Server → Add Remote Server，或直接编辑你的设置文件：

{
  "context_servers": {
    "xata": {
      "url": "https://api.xata.tech/mcp"
    }
  }
}

2. Zed 会提示你使用标准 MCP OAuth 流程对服务器进行身份验证。

Cline

1. 在 VS Code 中打开 Cline 并点击 MCP Servers 图标。
2. 在 Remote Servers 选项卡中，输入 xata 作为名称，输入 https://api.xata.tech/mcp 作为 URL，并选择 Streamable HTTP 作为传输方式。或者直接编辑配置 JSON：

{
  "mcpServers": {
    "xata": {
      "type": "streamableHttp",
      "url": "https://api.xata.tech/mcp"
    }
  }
}

[!NOTE]

传输类型必须为 streamableHttp（驼峰式）。省略它会导致 Cline 回退到旧版 SSE 传输方式，而 Xata MCP 服务器不支持该方式。

其他 MCP 客户端

任何 MCP 客户端只要支持以下内容即可连接：

• 通过 Streamable HTTP（而非 SSE）连接远程 MCP 服务器
• 支持动态客户端注册的 OAuth，或用于 API 密钥身份验证的自定义 HTTP 标头

请查阅你的客户端文档，了解在何处配置远程 MCP 服务器，并使用 https://api.xata.tech/mcp 作为 URL。

验证连接

连接后，向你的助手提问：

使用 Xata MCP 服务器查找用于列出分支的 REST API 操作。

助手应使用 {"query":"list branches"} 调用 search_operations，并返回 listBranches 操作，该操作可通过 call_read_operation 调用。如果能够做到，则说明连接正常。

可用工具

Xata MCP 服务器提供以下工具：

工具	描述
search_operations	按意图查找 Xata REST API 操作（例如“列出分支”或“邀请成员”）。
describe_operation	返回特定操作的参数以及请求/响应架构。
call_read_operation	调用只读的 Xata REST API 操作。
call_write_operation	调用创建或更新数据的 Xata REST API 操作。
call_destructive_operation	调用销毁数据或撤销访问权限的 Xata REST API 操作。需要 confirm=true。
run_sql	对分支运行 SQL。默认只读；会修改数据的语句需要同时提供 write=true 和 confirm=true。
describe_schema	列出分支的表和列。
list_skills	列出可用的 Xata 技能——用于常见多步骤任务的引导式工作流。
get_skill	阅读特定技能的说明。
search_xata	搜索 Xata 文档。
query_docs_filesystem_xata	按路径阅读 Xata 文档页面。

安全

• 对于交互式客户端，优先使用 OAuth；令牌有效期较短，可通过在客户端中断开服务器来撤销。
• 对于自动化，请使用专用的 API 密钥并定期轮换。
• 某些工具可以修改你的数据：call_write_operation 和 call_destructive_operation 可以更改或删除资源（后者需要 confirm=true），而 run_sql 在同时使用 write=true 和 confirm=true 调用时可以修改数据。在批准助手提议的操作之前，请先审查这些操作，并在任何写入或删除操作中保持人工参与。

故障排除

身份验证持续失败或循环。 从客户端中移除 Xata 服务器，重启客户端，然后重新添加服务器以触发全新的 OAuth 流程。

身份验证在浏览器中显示“Client not found”。 你的 MCP 客户端可能保存了一个在 Xata 身份验证服务器上已不再可用的 OAuth 注册。根据客户端的不同，移除并重新添加 MCP 服务器可能会保留此注册。请在客户端中清除 Xata 已保存的 OAuth 注册，然后重启 Xata MCP 服务器并再次进行身份验证，以允许全新的注册。

例如，在 VS Code 中：

1. 打开命令面板（Cmd+Shift+P / Ctrl+Shift+P）。
2. 运行 Authentication: Remove Dynamic Authentication Providers。
3. 选择与 Xata 关联的提供程序，保持无关的提供程序不变。
4. 重启 Xata MCP 服务器并再次完成身份验证。

服务器已连接但不显示任何工具。 请确保你已完成身份验证步骤——大多数工具需要有效会话才会显示。重新运行客户端的身份验证流程，然后刷新其工具列表。完整列表请参阅可用工具。

你的客户端完全无法连接。 确认 URL 完全为 https://api.xata.tech/mcp，并且你的客户端支持 Streamable HTTP。不支持仅 SSE 的客户端。

服务器未出现在你的客户端中。 检查客户端的 MCP 配置文件语法——JSON 结构因客户端而异（mcpServers 与 servers 与 context_servers，url 与 serverUrl）——并检查客户端的日志。大多数客户端在配置更改后需要完全重启。

本文档构建并托管于 Mintlify，一个开发者文档平台。