Nhost

Nhost MCP 服务

Nhost MCP 服务为任何 Nhost 项目添加 Agent 式接口。它将项目的 GraphQL API 公开为 MCP（模型上下文协议）服务，使 Claude、Cursor 等 AI 助手或任何兼容 MCP 的客户端都能查询和修改数据。

如果你基于 Nhost 构建，此服务可让用户通过 AI 助手与项目数据交互，无需编写自定义集成代码。将其与项目一同部署后，任何兼容 MCP 的客户端都能连接，并通过现有的 Nhost Auth 设置代表用户进行身份验证，在已定义的权限范围内处理数据。

工作原理

MCP 服务位于 AI 助手与 Nhost 项目的 GraphQL API 之间。它提供了三个可供助手调用的工具：

• get-schema - 检查 GraphQL 架构，让助手了解数据模型。返回可用操作的摘要，或特定查询／变更的完整 SDL。
• graphql-query - 对项目执行只读 GraphQL 查询。
• graphql-mutation - 执行 GraphQL 变更，以创建、更新或删除数据。

启动时，服务会从 GraphQL 端点获取架构摘要，并将其纳入 MCP 指令，让 AI 助手无需额外配置即可立即了解数据模型。

使用 OAuth2 进行身份验证

MCP 服务集成了 Nhost Auth，将其用作 OAuth2 授权服务，并遵循 MCP 授权规范。这意味着任何支持 OAuth2 的 MCP 客户端都能自动通过 Nhost 项目进行身份验证。

流程如下：

1. MCP 客户端通过从 MCP 服务获取 /.well-known/oauth-protected-resource 来发现身份验证要求。
2. 客户端将用户重定向到 Nhost Auth 授权端点进行登录（使用 PKCE 的授权码流程）。
3. 身份验证完成后，客户端将授权码交换为 JWT 访问令牌。
4. 后续所有 MCP 请求都会将 JWT 作为 Bearer 令牌携带。
5. MCP 服务通过 JWKS 验证 JWT 签名，检查颁发者和过期时间，然后在每个 GraphQL 请求中转发该令牌。
6. GraphQL 服务会根据 JWT 的声明强制执行行级和列级权限，因此 AI 助手只能访问已通过身份验证的用户有权查看的数据。

重要！需要启用 CIMD。

强制指定角色

--enforce-role 标志会限制 MCP 服务仅接受 x-hasura-default-role 声明与指定角色匹配的令牌。默认角色不同的请求会收到 403 Forbidden 响应。

例如，设置 --enforce-role=user_mcp 意味着只接受默认角色为 user_mcp 的令牌。如果你已为该角色配置了受限权限（例如，仅允许读取某些表），AI 助手就只能使用这些权限。

这样你可以：

• 创建一个专用角色（例如 user_mcp），并为 AI 访问设置受限权限。
• 允许 AI 助手读取数据，但禁止修改数据。
• 限制助手可见的表或列。
• 针对不同用例，以不同的角色配置运行多个 MCP 实例。

配置

所有标志都可以通过环境变量设置。

标志	环境变量	描述
--listen-addr	MCP_LISTEN_ADDR	HTTP 监听地址（默认值：:3000）
--debug	MCP_DEBUG	启用调试日志
--log-format-text	MCP_LOG_FORMAT_TEXT	将日志格式设为纯文本，而不是 JSON
--graphql-endpoint	MCP_GRAPHQL_ENDPOINT	GraphQL 端点 URL（必填）
--mcp-instructions	MCP_INSTRUCTIONS	服务级 MCP 指令
--query-instructions	MCP_QUERY_INSTRUCTIONS	graphql-query 工具的指令
--mutation-instructions	MCP_MUTATION_INSTRUCTIONS	graphql-mutation 工具的指令
--schema-instructions	MCP_SCHEMA_INSTRUCTIONS	get-schema 工具的指令
--auth-url	MCP_AUTH_URL	OAuth2 授权服务 URL（必填）
--realm	MCP_REALM	WWW-Authenticate 标头的 Realm
--enforce-role	MCP_ENFORCE_ROLE	强制要求 JWT 的默认 Hasura 角色与此值匹配
--browser-html	MCP_BROWSER_HTML	浏览器访问服务 URL 时提供的 HTML 内容

部署到 Nhost

要部署到 Nhost Run，可以使用下面的一键安装链接：

https://app.nhost.io/run-one-click-install?config=eyJuYW1lIjoibWNwIiwiaW1hZ2UiOnsiaW1hZ2UiOiJuaG9zdC9tY3A6MC4xLjAiLCJwdWxsQ3JlZGVudGlhbHMiOm51bGx9LCJjb21tYW5kIjpbIm1jcCJdLCJyZXNvdXJjZXMiOnsiY29tcHV0ZSI6eyJjcHUiOjEyNSwibWVtb3J5IjoyNTZ9LCJzdG9yYWdlIjpbXSwicmVwbGljYXMiOjEsImF1dG9zY2FsZXIiOm51bGx9LCJlbnZpcm9ubWVudCI6W3sibmFtZSI6Ik1DUF9BVVRIX1VSTCIsInZhbHVlIjoiaHR0cHM6Ly9TVUJET01BSU4uYXV0aC5SRUdJT04ubmhvc3QucnVuL3YxIn0seyJuYW1lIjoiTUNQX1JFQUxNIiwidmFsdWUiOiJodHRwczovL21jcC5hY21lLmNvbSJ9LHsibmFtZSI6Ik1DUF9HUkFQSFFMX0VORFBPSU5UIiwidmFsdWUiOiJodHRwOi8vaGFzdXJhLXNlcnZpY2U6ODA4MC92MS9ncmFwaHFsIn0seyJuYW1lIjoiTUNQX0lOU1RSVUNUSU9OUyIsInZhbHVlIjoiVGhlc2UgYXJlIHNvbWUgaW5zdHJ1Y3Rpb25zIGZvciB5b3VyIE1DUCBzZXJ2ZXIuIn0seyJuYW1lIjoiTUNQX0VORk9SQ0VfUk9MRSIsInZhbHVlIjoidXNlcl9tY3AifV0sInBvcnRzIjpbeyJwb3J0IjozMDAwLCJ0eXBlIjoiaHR0cCIsInB1Ymxpc2giOnRydWV9XSwiaGVhbHRoQ2hlY2siOm51bGx9

并根据需要进行编辑。请确保在 MCP_AUTH_URL 中设置正确的子域名和区域（如果使用自定义域名，则设置为自定义域名），将 MCP_REALM 设为 MCP 服务将使用的 URL，根据需要更改 MCP_INSTRUCTIONS，并更改或移除 MCP_ENFORCE_ROLE。

注意：请查看 releases 页面，并确保使用最新版本的服务。

或者，将 run-mcp.toml 添加到项目目录：

name = 'mcp'
command = ['mcp']

[image]
image = 'nhost/mcp:0.1.0'

[[environment]]
name = 'MCP_AUTH_URL'
value = 'https://local.auth.local.nhost.run/v1'

[[environment]]
name = 'MCP_REALM'
value = 'https://myapp.example.com'

[[environment]]
name = 'MCP_GRAPHQL_ENDPOINT'
value = 'http://hasura-service:8080/v1/graphql'

[[environment]]
name = 'MCP_INSTRUCTIONS'
value = 'This MCP server interacts with my application'

[[environment]]
name = 'MCP_ENFORCE_ROLE'
value = 'user_mcp'

[[ports]]
port = 3000
type = 'http'
publish = true

[resources]
replicas = 1

[resources.compute]
cpu = 125
memory = 256

然后按常规方式部署项目。MCP 服务将在已发布的端口上提供服务，任何兼容 MCP 的客户端都可以连接。

你也可以在本地尝试：

nhost up --run-service run-mcp.toml

连接 MCP 客户端

将 MCP 客户端指向服务 URL。例如，在 Claude Desktop 的配置中：

1. 前往“自定义” -> “连接器”
2. 点击 +，输入任意名称以及 MCP 服务所在的 URL，例如 https://mcp.acme.com
3. 点击“添加”
4. 连接后，你将被重定向到 Oauth2 的同意页面，以授权 Oauth2 客户端。