Integrate the client

The Agent Auth client sits between your agent and the server. It manages keys, handles registration, signs JWTs, and exposes protocol tools. There are three ways to integrate: the SDK (for embedding in your application), the CLI (for scripting and automation), and MCP (for AI tool ecosystems).

SDK

The Agent Auth SDK is a TypeScript library you embed directly in your application. It manages keypairs, handles discovery and registration, and signs requests automatically.

npm install agent-auth

import { AgentAuthClient } from "agent-auth";

const client = new AgentAuthClient({
  // optional: pre-configure providers
  providers: [
    { name: "bank", issuer: "https://auth.bank.com" }
  ],
  // optional: configure registry for search
  registry: "https://registry.agent-auth-protocol.com"
});

The SDK handles host keypair generation and storage, agent keypair management, JWT signing, discovery, and the full registration flow including approval polling.

CLI

The CLI is a command-line tool for managing agents, testing connections, and scripting Agent Auth workflows:

# Discover a provider
npx agent-auth discover https://bank.com

# Connect an agent
npx agent-auth connect bank --capabilities check_balance

# Execute a capability
npx agent-auth execute bank check_balance --args '{"account_id": "acc_123"}'

# Check agent status
npx agent-auth status bank

# Disconnect
npx agent-auth disconnect bank

The CLI stores host keypairs locally and manages agent state across invocations. It's useful for testing your server implementation and for scripting agent workflows in CI/CD pipelines.

MCP integration

The most common deployment model is running the client as an MCP server. AI tools like Claude Code, Cursor, and ChatGPT connect to MCP servers to access tools. When the Agent Auth client runs as an MCP server, all protocol tools are exposed as MCP tools that agents can call directly.

# Run as MCP server
npx agent-auth serve

Or configure in your MCP settings:

{
  "mcpServers": {
    "agent-auth": {
      "command": "npx",
      "args": ["agent-auth", "serve"]
    }
  }
}

This exposes all the standard tools — list_providers, search_providers, connect_agent, execute_capability, etc. — as MCP tools that any connected AI agent can use.

The MCP server model means agents don't need to know anything about Agent Auth. They just call MCP tools, and the client handles all the authentication, key management, and protocol details.

Connect and execute

The typical flow from an agent's perspective:

// 1. Discover or select a provider
const providers = await client.listProviders();

// 2. Connect (register an agent)
const agent = await client.connect({
  provider: "bank",
  capabilities: ["check_balance"],
  reason: "User wants to check their balance",
  mode: "delegated"
});
// → { agent_id: "agt_k7x9m2", status: "active", capabilities: [...] }

// 3. Execute capabilities
const result = await client.execute({
  provider: "bank",
  capability: "check_balance",
  arguments: { account_id: "acc_123" }
});
// → { balance: 1250.00, currency: "USD" }

Handling approval

When connecting to a new server for the first time, user approval is typically required. The client handles this by:

1. Receiving the verification URI and user code from the server
2. Presenting this to the user (opening a browser, displaying in terminal, etc.)
3. Polling the server's status endpoint until approved
4. Returning the active agent to the caller

Once the host is trusted, future agents requesting default capabilities are auto-approved — no user interaction needed.

Capability escalation

If an agent needs additional capabilities at runtime:

const result = await client.requestCapability({
  provider: "bank",
  capabilities: ["transfer_funds"],
  reason: "User asked to transfer money"
});
// Triggers approval flow if needed, returns updated grants

Escalated capabilities always require explicit user approval, even from trusted hosts.