agent-auth-mcp

Agent Auth MCP Tools

You have access to Agent Auth MCP tools for interacting with Agent Auth providers. Always prefer using these MCP tools for any agent authentication operations rather than making raw HTTP requests or writing custom code.

Starting the MCP Server

The MCP server is part of the CLI:

auth-agent mcp

Or with pre-configured providers:

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

Cursor / Claude Desktop configuration

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

Available Tools

The MCP server exposes 17 tools. Follow the numbered workflow below.

Step 1: Discovery — Find a Provider

Always start with list_providers. If empty, use search_providers or discover_provider.

Step 2: Capabilities — Understand What's Available

Step 3: Connect — Authenticate an Agent

Key parameters:

• capabilities — Array of capability names to request.
• mode — "delegated" (acts for a user, default) or "autonomous" (independent).
• preferred_method — "device_authorization" (default, opens browser) or "ciba" (backchannel notification).
• login_hint — User email for CIBA flow.
• force_new — Create a new connection even if one exists.

Step 4: Use the Agent

Host Management

Workflow Example

Here is the standard workflow for connecting to a provider and executing a capability:

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

Important Rules

• Never make raw HTTP requests to Agent Auth endpoints. Always use MCP tools.
• Always call list_providers first. This tells you what's already configured.
• Always call describe_capability before execute_capability. You need the input schema.
• Always call agent_status after connect_agent. The agent may be pending approval.
• Save the agent_id returned by connect_agent — every subsequent tool needs it.
• Use constraints when connecting to limit agent permissions — pass them in the capabilities parameter as objects with name and constraints fields.
• Handle approval flows. When connect_agent returns approval info (device code URL or CIBA), the user must approve before the agent becomes active. Poll agent_status to check.
• Errors return structured objects like { error: "message", code: "error_code" } — check these and retry or adjust accordingly.

Capability Constraints

When connecting, you can restrict what an agent can do with its capabilities:

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

Constraint types: eq (exact match), min/max (numeric bounds), in/not_in (allowed/blocked values).

When to Use CLI vs MCP

• Use MCP tools when operating inside an MCP-enabled environment (Cursor, Claude Code, Claude Desktop) — the tools are already available and integrated.
• Use the CLI when running from a terminal directly, scripting, or when MCP is not available.
• Both expose the same operations and share the same storage (~/.agent-auth/).