Nhost MCP 服务实战指南：把 Nhost 项目的 GraphQL API 接入 AI 助手-北京尧图网络

Nhost MCP 服务实战指南把 Nhost 项目的 GraphQL API 接入 AI 助手【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhostNhost 的开源 MCPModel Context Protocol服务为任何 Nhost 项目提供了一套智能体接口它以 MCP Server 的形式暴露项目自身的 GraphQL API让 Claude、Cursor 以及任何兼容 MCP 的客户端无需编写自定义集成代码即可对项目数据进行查询与变更。阅读本文后你将掌握该服务的三个核心工具get-schema、graphql-query、graphql-mutation、基于 Nhost Auth 的 OAuth2 授权流程、--enforce-role的角色收敛机制以及通过 Nhost Run 一键部署和本地调试的完整方案。服务定位与工作原理Nhost MCP 服务的定位很明确在 AI 助手与 Nhost 项目的 GraphQL API 之间充当一层薄薄的协议适配器。它本身不存储数据也不替代 Hasura GraphQL 引擎而是把 Hasura 暴露的 GraphQL 端点翻译成 MCP 客户端可以调用的工具集合。服务启动后会对外提供三个可被 AI 助手调用的工具定义见 services/mcp/tools/query.go 与 services/mcp/tools/schema.go工具名作用参数get-schema对 GraphQL 端点做 introspection让助手理解数据模型可返回可用操作摘要或针对指定查询/变更返回完整 SDLsummary布尔默认true、queries字符串数组、mutations字符串数组graphql-query对项目执行只读GraphQL 查询query必填字符串、variables对象graphql-mutation执行 GraphQL 变更用于创建、更新、删除数据query必填字符串、variables对象在启动阶段BuildServer见 services/mcp/server/server.go服务会通过tools.NewTool注册这三个工具并支持通过--mcp-instructions注入服务器级指令。启动后服务会先从 GraphQL 端点抓取一份 schema 摘要将其写入 MCP 的 instructions使 AI 助手在没有任何额外配置的情况下立即获得关于数据模型的上下文。工具注册时使用了完整的 MCP 工具注解Tool Annotation这在协议层面明确告知了客户端每个工具的语义graphql-queryReadOnlyHinttrue、DestructiveHintfalse、IdempotentHinttruegraphql-mutationReadOnlyHintfalse、DestructiveHinttrue、IdempotentHintfalseget-schema只读、幂等、非破坏。这些注解见 services/mcp/server/server_test.go 中的默认工具断言不仅帮助 AI 助手正确选择工具也是 MCP 协议合规性的重要组成。服务端还通过IsBrowserRequest判断 GET 请求的Accept头是否包含text/html识别浏览器访问返回一段可配置的 HTML 提示页避免普通用户误以为服务不可用。基于 Nhost Auth 的 OAuth2 认证MCP 服务与 Nhost Auth 集成将 Nhost Auth 作为OAuth2 授权服务器遵循 MCP Authorization 规范authorization code flow PKCE。这意味着任何支持 OAuth2 的 MCP 客户端都可以自动完成对 Nhost 项目的认证。完整认证流程如下实现位于 services/mcp/auth/auth.goMCP 客户端先请求 MCP 服务器上的/.well-known/oauth-protected-resource发现认证要求客户端将用户重定向到 Nhost Auth 的授权端点{auth-url}/oauth2/authorize进行登录authorization code flow with PKCECodeChallengeMethodsSupported为S256TokenEndpointAuthMethodsSupported为none认证通过后客户端用授权码在{auth-url}/oauth2/token换取 JWT 访问令牌支持authorization_code与refresh_token两种 grant之后的所有 MCP 请求都携带Authorization: Bearer JWTMCP 服务器从{auth-url}/.well-known/jwks.json拉取 JWKS校验 JWT 的签名、issuer即auth-url本身与过期时间见extractAndValidateToken同时启用jwt.WithIssuedAt()与jwt.WithExpirationRequired()校验通过的令牌被放入请求上下文并通过authorizationInterceptor见 services/mcp/tools/query.go原样转发到每一次 GraphQL 请求的Authorization头Hasura GraphQL 服务根据 JWT 中的 Hasura claims 强制执行行级、列级权限——AI 助手只能访问已认证用户被允许看到的数据。服务对外暴露两个 OAuth2 发现端点路由注册见 services/mcp/server/server.goGET /.well-known/oauth-authorization-server返回授权服务器元数据issuer、JWKS URI、authorization/token 端点、支持的 scopes/grants/code challenge 方法等GET /.well-known/oauth-protected-resource返回受保护资源元数据资源 URI、授权服务器列表、支持的 scopes。其中支持的 OAuth2 scope 由scopesForRole决定未设置--enforce-role时声明openid与graphql设置后则声明openid与graphql:role:enforce-role让授权服务器在令牌签发阶段即可体现角色约束。⚠️重要前置条件必须启用 Nhost Auth 的 CIMDClient-Initiated MCP 相关客户端能力否则 MCP 客户端无法自动完成上述 OAuth2 动态注册与授权流程。认证失败时缺失令牌、令牌无效中间件会返回401 Unauthorized并在WWW-Authenticate响应头中携带Bearer realm...与resource_metadata...两段信息引导客户端前往资源元数据端点重新走授权流程见writeUnauthorized。用 --enforce-role 收敛 AI 助手的权限--enforce-role标志用于强制 MCP 服务器只接受x-hasura-default-roleclaim 与指定值一致的令牌。当请求携带的默认角色不同时服务返回403 Forbidden。在checkRole实现services/mcp/auth/auth.go中服务从 JWT 的https://hasura.io/jwt/claims命名空间下读取x-hasura-default-role与--enforce-role指定值比对不一致即返回ErrRoleMismatch并中止请求。例如设置--enforce-roleuser_mcp后只有以user_mcp作为默认角色签发的令牌会被接受。如果为该角色配置了受限权限例如对某些表只读那么 AI 助手就会被严格限制在这些权限内。这个机制带来的典型收益创建专用角色如user_mcp并为其配置受限的 AI 访问权限允许 AI 助手读取数据但禁止修改限制助手可见的表或列范围为不同用例运行多个 MCP 实例每个实例使用不同的角色配置。从源码结构看--enforce-role还会同步影响两个发现端点的scopes_supported声明变为graphql:role:role使角色约束贯穿令牌签发—令牌校验全链路。配置项总览所有命令行 flag 均可通过环境变量设置flag 定义见 services/mcp/server/server.goFlag环境变量说明--listen-addrMCP_LISTEN_ADDRHTTP 监听地址默认:3000--debugMCP_DEBUG开启调试日志--log-format-textMCP_LOG_FORMAT_TEXT以纯文本而非 JSON 格式输出日志--graphql-endpointMCP_GRAPHQL_ENDPOINTGraphQL 端点 URL必填--mcp-instructionsMCP_INSTRUCTIONS服务器级 MCP 指令--query-instructionsMCP_QUERY_INSTRUCTIONS针对graphql-query工具的指令--mutation-instructionsMCP_MUTATION_INSTRUCTIONS针对graphql-mutation工具的指令--schema-instructionsMCP_SCHEMA_INSTRUCTIONS针对get-schema工具的指令--auth-urlMCP_AUTH_URLOAuth2 授权服务器 URL必填--realmMCP_REALMWWW-Authenticate头中的 realm--enforce-roleMCP_ENFORCE_ROLE强制 JWT 的默认 Hasura 角色等于该值--browser-htmlMCP_BROWSER_HTML浏览器访问服务 URL 时返回的 HTML 内容两点实现细节值得注意--graphql-endpoint与--auth-url被标记为Required: true缺省时BuildServer直接返回ErrGraphqlEndpointRequired错误并退出services/mcp/server/server.go三个工具的指令 flag 未设置时服务会使用各自的默认指令DefaultQueryInstructions、DefaultMutationInstructions、DefaultSchemaInstructions见 services/mcp/tools/query.go 与 services/mcp/tools/schema.go这些默认指令明确提示助手查询失败时重新获取 schema等行为约束。部署到 Nhost Run方式一一键安装链接Nhost 提供了一键安装链接可直接把该服务部署到 Nhost Run该链接预置了mcp镜像、环境变量与端口映射。部署后请按需修改将MCP_AUTH_URL中的 subdomain 与 region 改为你的项目实际值如使用自定义域名则填自定义域名格式形如https://subdomain.auth.region.nhost.run/v1将MCP_REALM设置为你将要使用的 MCP 服务 URL如https://mcp.acme.com按需修改MCP_INSTRUCTIONS按需修改或移除MCP_ENFORCE_ROLE。注意部署前建议查看 Nhost 的 releases 页面确认正在使用最新版本的服务镜像。方式二run-mcp.toml 声明式部署更推荐的方式是在项目目录中添加一个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要点说明command [mcp]对应服务二进制入口services/mcp/main.go 中server.Command(Version)注册的命令名即为mcpMCP_GRAPHQL_ENDPOINT指向 Nhost Run 集群内部的 Hasura 服务地址http://hasura-service:8080/v1/graphqlMCP_AUTH_URL指向 Nhost Auth 的 OAuth2 授权端点MCP_ENFORCE_ROLE设置为user_mcp即上文所述的角色收敛机制端口3000对外发布为http与默认监听地址:3000对应。部署完成后MCP 服务器会出现在发布的端口上任何 MCP 兼容客户端都可连接。本地调试在本地运行 Nhost CLI 时可以用 Nhost Run 服务的方式直接加载该配置nhost up --run-service run-mcp.toml该命令来自 CLI 的run命令组cli/cmd/run/dev.go会在本地开发环境中启动run-mcp.toml描述的服务便于在开发阶段验证 MCP 工具与认证流程。连接 MCP 客户端将 MCP 客户端指向服务器 URL 即可接入。以 Claude Desktop 为例进入自定义Customize→ Connectors点击输入任意名称以及 MCP 服务器所在 URL例如https://mcp.acme.com点击 Add 添加连接成功后会被重定向到 Nhost OAuth2 的 consent授权同意页面授权该 OAuth2 客户端后即可开始使用。此后 AI 助手便能通过三个工具与你的 Nhost 项目数据交互先get-schema了解数据模型再graphql-query只读查询需要时以graphql-mutation变更数据——而这一切都被 Nhost Auth 的令牌校验和 Hasura 的权限体系约束在已认证用户的授权范围内。延伸源码级安全机制与测试保障从源码看MCP 服务在工具调用前还叠加了一层 GraphQL 操作白名单校验。graphql-query与graphql-mutation的请求最终都会经过 cli/mcp/graphql/query.go 中的CheckAllowedGraphqlQuery用gqlparser解析 GraphQL 操作直接拒绝 subscription 操作对顶层 selection 字段与allowedQueries/allowedMutations白名单逐一比对支持*通配符放行任意操作。在 MCP 服务的实际调用中查询工具传入[]string{*}查询白名单变更工具传入[]string{*}变更白名单两者互不交叉——也就是说查询工具即使拿到 mutation 语句也无法执行从协议层到 GraphQL 层形成了双重约束。此外服务内置健康检查端点GET /healthz返回{status:ok}方便 Nhost Run 做存活探针日志中间件会从已认证 JWT 中提取sub与 Hasura claims 作为结构化日志字段sessionAttributes便于在调试时追踪哪个用户通过哪个角色发起了哪次调用。仓库中的 services/mcp/auth/auth_test.go 与 services/mcp/server/server_test.go 分别覆盖了认证中间件缺失令牌、非法 scheme、过期令牌、有效令牌及WWW-Authenticate响应头与工具注册默认/自定义指令、工具注解断言等关键路径可作为深入理解行为边界的参考。【免费下载链接】nhostThe Open Source Firebase Alternative with GraphQL.项目地址: https://gitcode.com/GitHub_Trending/nh/nhost创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Nhost MCP 服务实战指南：把 Nhost 项目的 GraphQL API 接入 AI 助手

相关推荐

MONAI 模块全景与核心亮点：从数据加载、网络训练到 Bundle、联邦学习与 Auto3dseg

基于SIFT特征匹配与HSV分割的交通标志识别MATLAB实现

FiftyOne 标注前数据策展（Pre-Annotation Curation）：从原始数据到高质量标注集

更多资讯

SpringBoot整合Nacos常见报错排查与解决方案

Comsol EBG能带计算与伪模式处理技术详解

游戏超分辨率替换：OptiScaler 让你在 DLSS、FSR、XeSS 之间任选，帧率与画质兼得

多阈值Otsu的MATLAB实现：从类间方差到递归分割实战

Presidio完整指南：免费实现PII检测与数据脱敏，三步跑通敏感信息匿名化

DataHub DataFlow 与 DataJob 实体管理实战：用 Python SDK 构建数据处理管线元数据

今日更新

基于MATLAB的CRI显色指数计算：从SPD光谱到Ra的完整流程

JSP+Servlet+MySQL博客系统源码部署与优化全攻略

蜂窝调度算法 MATLAB 实现：比例公平、轮询与最大 C/I 对比

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？