DOCUMENTATION · v0.12.2
The ai-auth-mcp command
@enzovezzaro/ai-auth-mcp (0.3.9) is a local MCP server. It lets a coding agent drive an AI Auth wallet identity through MCP tools. It speaks stdio by default, or Streamable HTTP on loopback. It does not connect to a hosted service. For the runtime, keystore and lifecycle details, see the agents guide.
Install and run#
npm install @enzovezzaro/ai-auth-mcp
npx -y @enzovezzaro/ai-auth-mcp --help
npx -y @enzovezzaro/ai-auth-mcp init --keystore-dir ~/.ai-auth/agent
The passphrase comes from AI_AUTH_PASSPHRASE or a terminal prompt. init creates the encrypted identity and prints only the public id.
Commands#
| Command | What it does |
|---|---|
serve | Start the MCP server. This is the default command. |
init | Create a new encrypted identity. |
whoami | Print the public id of the identity in the keystore. |
preview | Show the scopes a site asks for, without granting anything. |
unlink | Delete the identity, the saved room and the HTTP secret. |
Flags#
| Flag | Meaning |
|---|---|
--keystore-dir DIR | Identity directory. Default ~/.ai-auth/agent. |
--connect INPUT | Connect instruction, its JSON, a site URL, or @file. |
--origin URL --room NAME | Explicit alternative to --connect. |
--caps a,b | Capabilities to request, when not discovered from the site. |
--approve a,b | Exact scopes to grant without a TTY. Never more than the site requested. |
--auto-join | Join the room at startup. |
--resume | Restore the last room saved for this origin. Use with --connect or --origin; the saved room must match that origin's approved room. |
--code-mode | Add the ai_auth_code tool. |
--provide room | Publish agent.ping and agent.self. Needs tools.invoke. |
--no-manifest | Do not fetch /.well-known/ai-auth.json for a URL. |
--http PORT | Serve Streamable HTTP on 127.0.0.1:PORT instead of stdio. 0 picks a free port. |
--open-wallet | When approval is needed, open the wallet in a browser and wait for its signed consent on the loopback callback. Needs --http. |
--name NAME | Wallet and descriptor name. Default ai-auth-mcp. |
--yes | Confirm unlink without a prompt. |
--help | Print usage. |
Choosing a site#
--connect takes a copied connect instruction, a JSON descriptor, or a site URL. For a bare URL the CLI fetches <origin>/.well-known/ai-auth.json with the shared fetchDiscovery() helper and validates the strict v1 shape from site discovery: type: "ai-auth-discovery", v: 1, an exact origin, bounded capabilities, rooms, issuers and webmcp. The agent gets its room from the first entry in rooms (or default) and its capabilities from the document, with no guessing. The fetch is bound to the exact origin, follows no redirects and is capped at 16 KiB.
An older typeless { "origin", "room"?, "capabilities": [...], "walletUrl"? } manifest is still accepted for compatibility, but its result is marked source: "manifest-provisional" and provisional: true rather than presented as a validated v1 document. A typed document that fails validation is never relabelled as provisional. A URL or manifest grants nothing on its own. Use --origin, --room and --caps to skip discovery.
Tools#
The server registers a tool only when the site requested its scope and the owner approved that scope.
| Tool | Scope | What it does |
|---|---|---|
ai_auth_status | presence.read | Identity, room, connection state, peers and granted scopes. |
ai_auth_join | presence.read | Join the approved room. A different room needs a new approval. |
ai_auth_leave | presence.read | Leave the room and forget it. |
ai_auth_events | presence.read | Read a bounded ring of room events after a cursor. Content is untrusted. |
ai_auth_move | presence.read | Move the agent's cursor on the shared page. x and y run from 0 to 1. |
ai_auth_send | messages.send | Send signed text to the room or one peer. |
ai_auth_list_tools | tools.invoke | List WebMCP tools from the page and from other agents. |
ai_auth_invoke | tools.invoke | Call a listed tool. Its provider approves each call. |
ai_auth_act | tools.invoke | Publish a signed activity status. |
ai_auth_code | tools.invoke | With --code-mode only. Run a short script against the connection-checked API. |
Error codes#
ai_auth_invoke returns a machine-readable code from TOOL_ERROR_CODES: TOOL_UNAVAILABLE, SITE_DISCONNECTED, CATALOG_EXPIRED, AUTH_EXPIRED, CANCELLED, TIMEOUT, NOT_JOINED, DENIED.
Code Mode#
Code Mode is opt in. Start the server with --code-mode and it adds ai_auth_code alongside the other tools. It does not replace them.
A script may call aiAuth.status(), aiAuth.listTools(), aiAuth.events(), aiAuth.send(), aiAuth.move() and aiAuth.invoke(). It may not call join, leave or act. Use the MCP tools for those.
The code is capped at 8,000 JavaScript characters. It runs in a worker thread that the host terminates after 2 seconds. Guest code has no network, filesystem, process or imports. This is not a security boundary by itself, because the MCP process keeps the host's privileges. Do not run hostile code here.
HTTP mode#
--http PORT listens on 127.0.0.1:PORT. The printed endpoint contains a random secret in the path, /mcp/<secret>. That secret is the credential for the agent. The CLI keeps it in <keystore-dir>/http-secret with mode 0600 and reuses it after a restart. Share the URL only with the client you intend to drive the agent. If you tunnel the port, use a tunnel you control. Stop the process to end the agent's presence.
With --open-wallet, the first MCP connection opens the wallet in a browser window. The wallet shows the requesting site and exact scopes, and posts the signed consent back to a loopback /consent/<secret> endpoint on the same server. The CLI verifies the signature, audience, nonce and wallet id before granting any scope. The site dashboard then shows the agent as connected. No hosted gateway is involved; the local process must stay running.
A reachable endpoint does not prove a live site connection. See session lifecycle for the strict definition of connected.
Library use#
You can also build a server in process with createAIAuthMcpServer and connectAIAuthMcpStdio from @enzovezzaro/ai-auth-mcp. You supply the wallet, the actions, and the local approval callback. See the package README for the shape.