MCP and external-agent integration

Generated setup, tool catalog, and safe-use rules for MCP/external agent clients.

External agent clients (Claude Desktop, Cursor, ChatGPT-compatible clients, and other MCP/HTTP consumers) discover Walwarden capabilities through an agent-scoped API token and execute them against the authenticated REST API v1. The authoritative tool catalog is served from the live capability registry, not from this page: authenticated clients should read it from the API.

Surface version w4.2.0 (min client contract w4.2.0). Generated from packages/core/src/capabilityContract.ts.

Transport Status

There is no native MCP server transport (JSON-RPC initialize/tools/list/tools/call over streamable HTTP or SSE) yet, so a mcpServers.url entry in claude_desktop_config.json or .cursor/mcp.json cannot complete an MCP handshake against Walwarden today. A native MCP endpoint is planned but not yet shipped. Until it lands, integrate over the HTTP surface below: discover tools from GET /api/v1/mcp/tools and execute them through the REST API v1 (/api/v1/...).

Live Tool Discovery

Authenticated clients read the live catalog instead of trusting these docs for what a token can do:

curl -H 'Authorization: Bearer $WALWARDEN_API_KEY' \
  '$WALWARDEN_BASE_URL/api/v1/mcp/tools'

This is a plain JSON catalog (a GET, not an MCP tools/list call). The dashboard tRPC surface exposes the same catalog via capability.mcpTools for the web client.

Agent-Scoped Token Setup

Create an agent-scoped API token from the dashboard Settings · API tokens page or the walwarden CLI with clientKind=mcp_external, an explicit TTL, org binding, and the capability scopes for the tools you intend to call. Send it as Authorization: Bearer <token>. Tokens are least-privilege, revocable, and audited per #257; destructive or human-gated tools return a confirmation challenge instead of executing directly.

Tokens are least-privilege, listable, and revocable from the dashboard or CLI; every call is attributed in the audit chain.

Connecting A Client

Native mcpServers.url config blocks for Claude Desktop (claude_desktop_config.json), Cursor (.cursor/mcp.json), and ChatGPT-compatible desktop clients are intentionally omitted: they require the native MCP transport described under Transport Status, which has not shipped. Adding one now would point a client at an endpoint that cannot handshake.

For every supported client (claude-desktop, cursor, chatgpt-desktop, generic-mcp), integrate over the HTTP surface today:

Mint an agent-scoped token (see Agent-Scoped Token Setup) and send it as Authorization: Bearer $WALWARDEN_API_KEY.
Discover available tools from GET $WALWARDEN_BASE_URL/api/v1/mcp/tools.
Execute a tool by calling its REST API v1 route (see the API reference). Tools whose route scope is none in the table below are advisory or not yet exposed as a live route; do not invoke them.

Callable Tools

Tool	Risk	Capability scope	Route scope	Human gate
`walwarden.audit.inspect`	`read_only`	`capability:audit.inspect`	none	`none`
`walwarden.backup.trigger`	`safe_write`	`capability:backup.trigger`	`backups:trigger`	`none`
`walwarden.destination.preflight`	`sensitive_write`	`capability:destination.preflight`	none	`none`
`walwarden.evidence.export`	`sensitive_write`	`capability:evidence.export`	none	`confirmation_required`
`walwarden.notification.check`	`read_only`	`capability:notification.check`	none	`none`
`walwarden.restore.progress`	`read_only`	`capability:restore.progress`	none	`none`
`walwarden.worker.check`	`read_only`	`capability:worker.check`	none	`none`

Tools with a human gate other than none return a confirmation challenge instead of executing directly. An agent must surface that challenge to a human before retrying.

Advisory (Contract-Only) Tools

These tools describe diagnosis/intelligence capabilities an agent can reason about, but they are not live-callable routes yet. Do not claim a live diagnosis/remediation action through them.

Tool	Summary
`walwarden.diagnostics.diagnose`	Return typed health findings and safe next capabilities for a database, destination, worker, or backup job.
`walwarden.environment.verify`	Check whether the current client has the tools, auth, and network reachability needed for an operation.
`walwarden.errors.explain`	Turn a stable error code and debug evidence into safe next actions and human-readable context.
`walwarden.recovery.disable`	Close a future logical recovery window with an explicit close reason.
`walwarden.recovery.enable`	Create a future logical recovery window anchored by a full baseline snapshot before transaction tailing begins.
`walwarden.recovery.preflight`	Return contract-only source and destination eligibility metadata for a future logical recovery window.
`walwarden.recovery.restore`	Future restore flow that replays a full baseline snapshot plus transaction segments to an explicit target.
`walwarden.recovery.status`	Read future logical recovery window state, schema digest, replay cursor, and proof metadata.

Forbidden Claims

Do not claim a native MCP server transport or a working mcpServers.url endpoint; none has shipped. Integrate over GET /api/v1/mcp/tools plus the REST API v1.
Do not expose or invoke a tool that is not in the live /api/v1/mcp/tools catalog.
Do not execute a human-gated or destructive tool without surfacing the confirmation challenge to a human.
Do not treat this page as the authority for live actions; the live capability registry is authoritative for authenticated clients.
Do not claim PITR, continuous backup, or unattended restore drills through any tool.
Do not claim recoverability from backup completion alone; check restore/evidence semantics first.