OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add better-auth/agent-auth --skill agent-auth-mcp
Use the Agent Auth MCP tools to discover providers, connect agents, manage capabilities, and execute operations through the MCP protocol. Use when working inside an MCP-enabled environment (Cursor, Claude Code, etc.) and need to authenticate agents, execute capabilities, or interact with Agent Auth providers.
npx skills add better-auth/agent-auth --skill agent-auth-mcp
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.
The MCP server is part of the CLI:
Or with pre-configured providers:
The MCP server exposes 17 tools. Follow the numbered workflow below.
| 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.
| 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. |
| 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.| 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. |
| 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. |
Here is the standard workflow for connecting to a provider and executing a capability:
list_providers first. This tells you what's already configured.describe_capability before execute_capability. You need the input schema.agent_status after connect_agent. The agent may be pending approval.agent_id returned by connect_agent — every subsequent tool needs it.capabilities parameter as objects with name and constraints fields.connect_agent returns approval info (device code URL or CIBA), the user must approve before the agent becomes active. Poll agent_status to check.{ error: "message", code: "error_code" } — check these and retry or adjust accordingly.When connecting, you can restrict what an agent can do with its capabilities:
Constraint types: eq (exact match), min/max (numeric bounds), in/not_in (allowed/blocked values).
~/.agent-auth/).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{
"provider": "https://api.example.com",
"capabilities": [
"read_data",
{
"name": "transfer_money",
"constraints": {
"amount": { "max": 1000, "min": 1 },
"currency": { "in": ["USD", "EUR"] }
}
}
]
}