通过MCP连接

机器集成以服务账号身份进行认证，使用OAuth client_credentials授权方式；对于只能发送固定请求头的客户端，也可使用静态API密钥。无需浏览器、用户会话或交互式授权同意。

1. 创建服务账号

由管理员在管理 → 服务账号中执行以下操作：

1. 请输入能标识该集成的显示名称，例如“Jira Sync”，而不是“api”。该名称会显示在审计历史中。
2. 点击创建。客户端密钥和API密钥仅显示一次，请立即复制。如果丢失，请使用重新签发密钥，两者均无法找回。

服务账号的ID即client_id，可以安全地保存在配置中。密钥则不然，请像对待密码一样妥善保管。

2. 授予其Brain访问权限

新建的服务账号可以通过身份验证，但看不到任何内容。访问权限需由管理员按Brain授予：在管理 → Brain中打开对应Brain，进入其服务账号访问权限部分。注意这是管理端的Brain页面；面向用户的Brain页面只管理用户和用户组的访问权限，不管理服务账号。

选择服务账号并设置访问级别：

按最小权限授予。只用于回答问题的智能体应设为read，这样即使检索内容中含有提示词注入，也无法导致写入。

3. 获取访问令牌

POST /brain/{brain_id}/token。支持表单编码或JSON格式。访问令牌是Bearer JWT，有效期为1小时；刷新令牌有效期为30天。

curl -X POST https://hive.example.com/brain/$BRAIN_ID/token \
  -d grant_type=client_credentials \
  -d client_id=$HIVE_CLIENT_ID \
  -d client_secret=$HIVE_CLIENT_SECRET

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOi..."
}

如需在不重新发送密钥的情况下轮换令牌，请使用refresh_token以grant_type=refresh_token发起请求。刷新令牌在使用后会轮换，请保存新的刷新令牌。

刷新令牌与账号当前的密钥绑定。密钥重新签发或到期后，刷新请求会返回invalid_grant，此时请使用当前密钥，通过grant_type=client_credentials申请新令牌。请确保集成始终能获取客户端密钥，仅凭刷新令牌无法恢复访问。

4. 调用工具

MCP端点为POST /brain/{brain_id}/mcp，采用基于Streamable HTTP传输的JSON-RPC 2.0。请将访问令牌作为Bearer请求头发送，并同时接受两种内容类型：

curl -X POST https://hive.example.com/brain/$BRAIN_ID/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "aiqbee_search",
      "arguments": {"query": "what did we decide about rate limiting?"}
    }
  }'

tools/list会返回完整的工具集及其schema，便于以编程方式构建工具定义，而无需硬编码。

API密钥

部分智能体平台无法执行令牌交换，只能在每个请求上附加一个固定的请求头。为此，服务账号还附带一个API密钥，它与客户端密钥同时签发，到期时间也相同。只要客户端支持，请优先使用客户端凭据（见上文）。

在X-Api-Key中携带密钥，即可调用任意MCP端点https://<hive>/brain/<brain-id>/mcp，无需申请令牌：

X-Api-Key: <api-key>

curl -X POST https://<hive>/brain/<brain-id>/mcp \
  -H "X-Api-Key: $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• 该密钥的权限与服务账号完全相同：相同的Brain访问权限、相同的权限层级，以及相同的allow_mcp_editing要求。
• 密钥必须通过X-Api-Key发送。以Authorization: Bearer令牌形式发送会被拒绝，并返回相应提示。
• 401表示密钥错误、已撤销或已过期，请更换密钥。503并带有Retry-After表示Hive当时无法验证该密钥，请重试，无需重新签发任何内容。
• 该密钥与客户端密钥的到期时间相同，每次重新签发客户端密钥时都会随之轮换。
• 在API密钥功能推出之前创建的服务账号，将在下次重新签发密钥时获得API密钥。

也可以用密钥换取访问令牌：向POST /brain/<brain-id>/token发送grant_type=api_key和api_key=<api-key>，将返回有效期1小时的访问令牌，不返回刷新令牌。

通过grant_type=api_key获取的令牌即使在密钥重新签发后，仍在到期前保持有效（最长1小时）；而直接在X-Api-Key中发送的密钥会在下一次请求时立即失效。

VS Code（SSH远程/无界面环境）

如果OAuth登录无法打开浏览器，可将密钥作为请求头写入mcp.json，并通过掩码输入提示避免将其明文保存在文件中：

{
  "inputs": [
    { "id": "hive-api-key", "type": "promptString",
      "description": "Hive API key", "password": true }
  ],
  "servers": {
    "aiqbee-hive": {
      "type": "http",
      "url": "https://<hive>/brain/<brain-id>/mcp",
      "headers": { "X-Api-Key": "${input:hive-api-key}" }
    }
  }
}

从Azure AI Foundry连接

Foundry为MCP工具提供了多种身份验证方式，只有一种适用于服务账号。

1. 在Hive中，前往管理 → 服务账号创建服务账号，并复制创建时显示的API密钥。每个集成使用一个服务账号，这样撤销时不会影响其他集成。
2. 为其授予智能体要使用的Brain的访问权限（见上方第2步）。服务账号不会获得任何隐式访问权限。
3. 在Foundry门户中打开您的项目，前往Build → Tools，然后选择Add tool → Custom → Model Context Protocol。
4. 填写连接信息：端点https://<hive>/brain/<brain-id>/mcp，Authentication选择Key-based，Credential name填X-Api-Key，Credential value填您的API密钥。然后选择Connect。

注意事项

• 凡是能访问该Foundry项目的人，都能读取存储在项目连接中的凭据。请为每个集成单独使用一个最小权限的服务账号。
• 密钥会在客户端密钥的到期日失效。请提前设置提醒：Foundry以静态方式存储该值，届时需要有人手动粘贴新值。
• Require approval默认为always。若一律设为never，写入和删除操作也会被自动批准；因此应逐一列出只读工具，所有会写入的工具保持always。
• 使用Brain专属端点，这样工具架构中就不再需要brain_id参数，模型出错的机会也更少。

最简Python客户端

大多数MCP SDK会自动处理这些。如果手动实现，需要处理的内容只有这么少：

import os, httpx

BASE     = os.environ["HIVE_BASE_URL"]
BRAIN_ID = os.environ["HIVE_BRAIN_ID"]


class Hive:
    """Thin Hive MCP client. Fetches a token lazily and retries once on 401."""

    def __init__(self) -> None:
        self._client = httpx.Client(timeout=30)
        self._token: str | None = None

    def _get_token(self) -> str:
        r = self._client.post(
            f"{BASE}/brain/{BRAIN_ID}/token",
            data={
                "grant_type": "client_credentials",
                "client_id": os.environ["HIVE_CLIENT_ID"],
                "client_secret": os.environ["HIVE_CLIENT_SECRET"],
            },
        )
        r.raise_for_status()
        return r.json()["access_token"]

    def call(self, tool: str, **arguments: object) -> dict:
        if self._token is None:
            self._token = self._get_token()

        def _post() -> httpx.Response:
            return self._client.post(
                f"{BASE}/brain/{BRAIN_ID}/mcp",
                headers={
                    "Authorization": f"Bearer {self._token}",
                    "Accept": "application/json, text/event-stream",
                },
                json={
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {"name": tool, "arguments": arguments},
                },
            )

        response = _post()
        if response.status_code == 401:      # token expired mid-session
            self._token = self._get_token()
            response = _post()
        response.raise_for_status()
        return response.json()


hive = Hive()
print(hive.call("aiqbee_search", query="rate limiting decision"))

故障排查