agent-auth-mcp

Agent Auth MCP 工具

你可以使用 Agent Auth MCP 工具与 Agent Auth 提供方交互。执行任何 Agent 身份验证操作时，始终优先使用这些 MCP 工具，而不是发送原始 HTTP 请求或编写自定义代码。

启动 MCP 服务

MCP 服务是 CLI 的一部分：

auth-agent mcp

或使用预配置的提供方：

auth-agent mcp --url https://api.example.com

Cursor / Claude Desktop 配置

{
  "mcpServers": {
    "auth-agent": {
      "command": "npx",
      "args": ["@auth/agent-cli", "mcp", "--url", "https://api.example.com"]
    }
  }
}

可用工具

MCP 服务提供 17 个工具。请按照以下编号工作流操作。

第 1 步：发现 — 查找提供方

工具	参数	使用时机
list_providers	（无）	**首先调用此工具。**列出所有已发现/已配置的提供方。
search_providers	intent（必填）	按名称或意图搜索目录（例如“部署 Web 应用”“vercel”）。
discover_provider	url（必填）	根据 URL 查找特定提供方。仅在列表/搜索没有帮助时使用。

**始终从 list_providers 开始。**如果结果为空，请使用 search_providers 或 discover_provider。

第 2 步：能力 — 了解可用功能

工具	参数	使用时机
list_capabilities	provider（必填）、query、agent_id、limit、cursor	列出提供方的能力。
describe_capability	provider、name（必填）、agent_id	获取完整定义，包括输入架构。执行前务必调用。

第 3 步：连接 — 对 Agent 进行身份验证

工具	参数	使用时机
connect_agent	provider（必填）、capabilities、mode、name、reason、preferred_method、login_hint、binding_message、force_new	将 Agent 连接到提供方。返回 agent_id。

关键参数：

• capabilities — 要申请的能力名称数组。
• mode — "delegated"（代表用户操作，默认值）或 "autonomous"（独立操作）。
• preferred_method — "device_authorization"（默认值，打开浏览器）或 "ciba"（后端通道通知）。
• login_hint — CIBA 流程所用的用户邮箱。
• force_new — 即使已存在连接，也创建新连接。

第 4 步：使用 Agent

工具	参数	适用场景
execute_capability	agent_id、capability（必填）、arguments	执行已授权的能力。
agent_status	agent_id（必填）	检查 Agent 状态、授权和约束。
sign_jwt	agent_id（必填）、capabilities、audience	为手动使用签署 Agent JWT。
request_capability	agent_id、capabilities（必填）、reason、preferred_method、login_hint、binding_message	请求额外的能力。
disconnect_agent	agent_id（必填）	撤销 Agent。
reactivate_agent	agent_id（必填）	重新激活已过期的 Agent。

主机管理

工具	参数	适用场景
enroll_host	provider、enrollment_token（必填）、name	使用一次性令牌注册主机。
rotate_agent_key	agent_id（必填）	轮换 Agent 的密钥对。
rotate_host_key	issuer（必填）	轮换提供方的主机密钥对。

工作流示例

以下是连接到提供方并执行一项能力的标准工作流：

1. list_providers
   → See what providers are already known

2. search_providers({ intent: "deploy web apps" })
   → Find a provider if none are known (or discover_provider with a URL)

3. list_capabilities({ provider: "https://api.example.com" })
   → See what the provider offers

4. describe_capability({ name: "deploy_app", provider: "https://api.example.com" })
   → Understand the input schema before executing

5. connect_agent({ provider: "https://api.example.com", capabilities: ["deploy_app"], name: "deploy-bot" })
   → Authenticate and get an agent_id
   → If approval is required, the user will be prompted

6. agent_status({ agent_id: "..." })
   → Confirm the agent is active and capabilities are granted

7. execute_capability({ agent_id: "...", capability: "deploy_app", arguments: { app: "my-app", env: "production" } })
   → Run the capability with the correct arguments

重要规则

• 切勿向 Agent Auth 端点发送原始 HTTP 请求。 始终使用 MCP 工具。
• 始终先调用 list_providers。 这会显示已配置的内容。
• 始终在调用 execute_capability 前调用 describe_capability。 你需要输入架构。
• 始终在调用 connect_agent 后调用 agent_status。 Agent 可能正在等待审批。
• 保存 connect_agent 返回的 agent_id——后续每个工具都需要它。
• 连接时使用约束来限制 Agent 的权限——在 capabilities 参数中传入带有 name 和 constraints 字段的对象。
• 处理审批流程。 当 connect_agent 返回审批信息（设备代码 URL 或 CIBA）时，用户必须先批准，Agent 才会激活。轮询 agent_status 以查看状态。
• 错误会返回结构化对象，例如 { error: "message", code: "error_code" }——请检查这些对象，并据此重试或调整。

能力约束

连接时，你可以通过能力限制 Agent 可执行的操作：

{
  "provider": "https://api.example.com",
  "capabilities": [
    "read_data",
    {
      "name": "transfer_money",
      "constraints": {
        "amount": { "max": 1000, "min": 1 },
        "currency": { "in": ["USD", "EUR"] }
      }
    }
  ]
}

约束类型：eq（精确匹配）、min/max（数值边界）、in/not_in（允许/禁止的值）。

何时使用 CLI 与 MCP

• 在启用了 MCP 的环境中操作时（Cursor、Claude Code、Claude Desktop），请使用 MCP 工具——这些工具已可用并集成。
• 直接从终端运行、编写脚本或无法使用 MCP 时，请使用 CLI。
• 两者提供相同的操作，并共享相同的存储位置（~/.agent-auth/）。