warden AGENTS.md

Warden — agent guide

This file orients an autonomous agent (LLM, AI assistant, automation script) that needs to call services through Warden. Operators looking to set up Warden, mount providers, or onboard credentials should read the docs — start with Providers and the per-backend guides under docs/provider-backends/; this tree is for the consumer side.

Where to start

Warden runs its own MCP discovery server at /v1/sys/mcp. Point your MCP client at it (for Claude Code, claude mcp add), presenting your identity — a bearer JWT (Authorization: Bearer <jwt>) or an mTLS client certificate — and, for a sub-namespace, the X-Warden-Namespace header. It needs no role: it authorizes on the identity you present. It exposes two tools:

• list_roles — the roles your identity can assume, each with an operator-written description. This is your menu.
• get_skill — given a skill name, returns that skill: the markdown recipe for driving the role's provider.

The description on each role carries what you need: the skill name, and — for a non-MCP provider — the role's gateway URL (relative; prepend $WARDEN_ADDR). For example: "read app secrets (skill: vault, url: /v1/vault/role/read-secret/gateway/)".

The agent loop

[ connect MCP client to /v1/sys/mcp ]   ← identity in the connection
       │
       ▼
[ list_roles ]                          ← which roles can I assume?
       │
       ▼
[ match task → pick a role ]            ← read descriptions; choose the fit
       │
       ▼
[ get_skill <name-from-description> ]   ← the per-provider recipe
       │
       ▼
[ act under the chosen role ]

How you act depends on the provider kind. Your role is the role/<role>/ segment of the gateway URL, so you pick a role by targeting that role's URL — the selector that works for every client. (X-Warden-Role is a header override, usable only where the client sets per-call headers — not an MCP tool call, whose headers are fixed and which carries no role.)