aauth-mcp

AAuth for MCP

TypeScript packages for adding AAuth to MCP servers and agents.

AAuth is an agent-aware authentication protocol that lets AI agents prove their identity and obtain authorization using HTTP Message Signatures and JWTs.

Packages

| Package | Description | |---------|-------------| | @aauth/bootstrap | CLI for setting up AAuth agent keys, person server registration, and hosting | | @aauth/fetch | CLI for making AAuth-authenticated HTTP requests | | @aauth/mcp-agent | Agent-side AAuth: signed fetch, challenge-response, token exchange | | @aauth/mcp-server | Server-side AAuth: token verification, challenge building, resource tokens | | @aauth/local-keys | Library for managing AAuth agent signing keys across hardware and software backends | | @aauth/hardware-keys | Native bindings for YubiKey PIV and macOS Secure Enclave | | @aauth/mcp-stdio | stdio-to-HTTP proxy with AAuth signatures | | @aauth/mcp-openclaw | OpenClaw plugin for AAuth-authenticated MCP connections |

How It Works

Agent                        Resource Server              Auth Server
  |                                |                          |
  |--- signed request ------------>|                          |
  |                                |                          |
  |<-- 401 + resource_token -------|                          |
  |        + auth-server URL       |                          |
  |                                |                          |
  |--- signed POST (resource_token) ------------------------->|
  |                                                           |
  |<-- auth_token --------------------------------------------|
  |                                |                          |
  |--- signed request ------------>|                          |
  |    + auth_token                |                          |
  |                                |-- verify signature       |
  |                                |-- verify auth_token      |
  |                                |-- check key binding      |
  |<-- 200 OK ---------------------|                          |

1. Agent sends a signed HTTP request to the resource server 2. Resource responds with 401 + a resource_token and auth server URL 3. Agent exchanges the resource_token at the auth server (signed request) 4. Auth server returns an auth_token (or 202 for interactive flows) 5. Agent retries with the auth_token — resource verifies signature, token, and key binding

All requests are signed with HTTP Message Signatures (RFC 9421) using Ed25519. Tokens are JWTs with aa-agent+jwt, aa-auth+jwt, and aa-resource+jwt types.

Quick Start

Agent side

import { createAAuthFetch } from '@aauth/mcp-agent'

const fetch = createAAuthFetch({
  getKeyMaterial: async () => ({
    signingKey: privateKeyJwk,
    signatureKey: { type: 'jwt', jwt: agentToken }
  })
})

const response = await fetch('https://resource.example/api')
// Handles 401 challenges, token exchange, and retry automatically

Server side

import { verifyToken, buildAAuthHeader, createResourceToken } from '@aauth/mcp-server'

// Verify an incoming signed request's token
const result = await verifyToken({ jwt, httpSignatureThumbprint })

// Build a 401 challenge
const header = buildAAuthHeader('auth-token', { resourceToken, authServer })

// Create a resource token for the challenge
const token = await createResourceToken({ resource, authServer, agent, agentJkt }, sign)

Local development

# Register an agent provider: generate a key, bind it, and bind the default
# person server (person.hello.coop)
npx @aauth/bootstrap create <your-agent-provider-url>

See @aauth/bootstrap for the full setup flow.

Protocol Support

This implementation covers the core AAuth protocol flows. The following spec features are not yet supported:

• Call chaining — multi-hop delegation where a resource acts as an agent to call downstream resources with upstream_token
• AS federation (four-party mode) — PS-to-Access-Server federation with requirement=claims for identity claim exchange

Specification

The AAuth protocol specification: github.com/dickhardt/AAuth

License

MIT