agent-auth-mcp

by better-auth

Use the Agent Auth MCP tools to discover providers, connect agents, manage capabilities, and execute operations through the MCP protocol. Use when working… npx skills add https://github.com/better-auth/agent-auth --skill agent-auth-mcp Download ZIPGitHub51

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

Tool Parameters When to use list_providers (none) Call this first. Lists all discovered/configured providers. search_providers intent (required) Search the directory by name or intent (e.g. "deploy web apps", "vercel"). discover_provider url (required) Look up a specific provider by URL. Only use if list/search didn't help.

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

Step 2: Capabilities — Understand What's Available

Tool Parameters When to use list_capabilities provider (required), query, agent_id, limit, cursor List capabilities for a provider. describe_capability provider, name (required), agent_id Get full definition including input schema. Always call before executing.

Step 3: Connect — Authenticate an Agent

Tool Parameters When to use connect_agent provider (required), capabilities, mode, name, reason, preferred_method, login_hint, binding_message, force_new Connect an agent to a provider. Returns agent_id.

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

Tool Parameters When to use execute_capability agent_id, capability (required), arguments Execute a granted capability. agent_status agent_id (required) Check agent status, grants, and constraints. sign_jwt agent_id (required), capabilities, audience Sign an agent JWT for manual use. request_capability agent_id, capabilities (required), reason, preferred_method, login_hint, binding_message Request additional capabilities. disconnect_agent agent_id (required) Revoke an agent. reactivate_agent agent_id (required) Reactivate an expired agent.

Host Management

Tool Parameters When to use enroll_host provider, enrollment_token (required), name Enroll a host with a one-time token. rotate_agent_key agent_id (required) Rotate an agent's keypair. rotate_host_key issuer (required) Rotate the host keypair for a provider.

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/).