接入 MCP 数据服务

在 MCP 客户端里填入 MCP 地址（https://dev.thuwater.com/mcp/data）、用 THWater 专用 MCP 账号登录一次即可开始使用；脚本对接需要请求 openid profile pg-mcp-audience 三个 scope，动态注册（DCR）客户端必须在注册报文中声明这三个 scope。

MCP 数据服务不需要安装任何软件，也不需要手工配置 Token：客户端负责发现登录入口、引导登录、自动续期。下面按"客户端接入"和"脚本接入"两条路说明。

开始之前

• 一个支持 MCP 的客户端（能填 Streamable HTTP 地址即可）；
• 一个已开通 MCP 数据权限的 THWater 账号（用 SSO 登录，不需要单独的密码）；
• 网络能访问 dev.thuwater.com 与 sso.thuwater.com。

第 1 步：填服务器地址

以 mcp.json 形式的客户端为例：

{
  "mcpServers": {
    "thwater-data": {
      "type": "streamable-http",
      "url": "https://dev.thuwater.com/mcp/data"
    }
  }
}

第 2 步：完成一次登录

首次连接时会发生这些事，都是自动的：

1. 客户端调用接口，服务端返回 401 并附带登录入口地址（WWW-Authenticate: Bearer resource_metadata="…"）；
2. 支持自动发现的客户端读取该地址，找到 THWater 统一登录（SSO）服务，并自动打开浏览器；
3. 你在浏览器里用 THWater 账号登录，并点击同意授权（密码只输入到 SSO 页面，MCP 服务全程看不到）；
4. 客户端拿到 Bearer 令牌并重新发起请求，连接建立。令牌 15 分钟有效，客户端会用 refresh token 自动续期，你不需要管。

第 3 步：确认连接成功

连接成功后，先问一个不涉及具体项目的问题来验证权限范围：

我现在能看哪些项目？

如果返回了项目清单（例如"THWater智慧排水监测"），说明账号、权限、登录全部正常。接下来就可以按「使用示例」里的方式提问了。

脚本 / CLI 接入

程序对接时不要共用个人密码：要么申请服务账号，要么走 OAuth 的设备码/授权码流程获取令牌，然后带 Authorization: Bearer <token> 调用接口。

curl -s -X POST https://dev.thuwater.com/mcp/data \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

申请令牌时请求的 scope 必须是：

openid profile pg-mcp-audience        # 需要 refresh token 时再加 offline_access

若平台已提供固定的 client_id/secret，直接使用即可。自行对接时也可让客户端通过 OAuth 动态客户端注册（RFC 7591，DCR）登记，注册报文必须一次性声明 scope 与回调地址：

curl -s -X POST https://sso.thuwater.com/realms/thdatalake/clients-registrations/openid-connect \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "my-mcp-client",
    "grant_types": ["authorization_code"],
    "response_types": ["code"],
    "redirect_uris": ["http://127.0.0.1:8973/callback"],
    "token_endpoint_auth_method": "client_secret_basic",
    "scope": "openid profile pg-mcp-audience"
  }'

然后走标准授权码流程 + PKCE：拼接 SSO 授权链接（scope=openid profile pg-mcp-audience，附 state 与 code_challenge）→ 浏览器打开链接、用 THWater 账号登录并点「是」同意 → 回调地址拿到 code → 换取令牌：

curl -s -X POST https://sso.thuwater.com/realms/thdatalake/protocol/openid-connect/token \
  -u "<client_id>:<client_secret>" \
  -d "grant_type=authorization_code&code=<code>\
        &redirect_uri=http%3A%2F%2F127.0.0.1%3A8973%2Fcallback\
        &code_verifier=<pkce_verifier>"

拿到令牌后，带上 Authorization: Bearer <token> 按上文 curl 调用即可（15 分钟有效，过期需重新走授权流程，或申请时加 offline_access 用 refresh token 续期）。