# For AI agents

These docs are designed to be read by LLMs and coding agents as well as people. The vault itself treats AI agents as first-class identities: an agent gets the same policy, freeze, and audit coverage as any human or automated system.

## Reading the docs as an agent

* **`/llms.txt`** is a concise, link-indexed map of the site.
* **`/llms-full.txt`** is the full docs as a single Markdown file.
* Append `.md` to any page URL for clean Markdown. For example, this page is available at `/introduction/for-ai-agents.md`.
* Every page also has "copy as Markdown" and "open in Claude" / "open in ChatGPT" actions in the top bar.

## Using the API from an agent

The vault is a REST API described by an OpenAPI spec. Hand the spec directly to your agent:

* **OpenAPI spec:** download the latest spec at [`/specs/latest/openapi.json`](/specs/latest/openapi.json) and hand it to your agent, or browse it interactively (with a YAML download) in the [API Reference](/api-reference).

The spec includes the complete authentication algorithm (Ed25519 request signing), all endpoints, and all request and response schemas.

The [Developer Guide](/develop/overview) covers:

* Creating a Machine User and generating an Ed25519 key pair.
* Building and signing a valid request.
* Calling `GET /v1/whoami` to check what the agent is permitted to do before attempting an action.

## MCP server (documentation)

This documentation site exposes an MCP server at `/api/mcp`. Point an MCP-compatible client (Claude, Cursor, or similar) at it so your agent can search and read these docs in context while it builds an integration. It serves the documentation; requests to the vault itself go through the REST API described above.

### Claude Desktop configuration

Add the following to your `claude_desktop_config.json` (replace the host with your docs deployment):

```json
{
  "mcpServers": {
    "crypto-vault-docs": {
      "type": "http",
      "url": "https://vault.docs.sodot.dev/api/mcp"
    }
  }
}
```

### Cursor configuration

Add the following to your Cursor MCP settings (`.cursor/mcp.json` or the Cursor settings UI):

```json
{
  "mcpServers": {
    "crypto-vault-docs": {
      "type": "http",
      "url": "https://vault.docs.sodot.dev/api/mcp"
    }
  }
}
```

Once connected, your agent can pull the relevant documentation on demand while you build against the API.

## What an agent can do in the vault

An AI agent is a Machine User. It authenticates with an Ed25519 key and API key, and every mutating request it makes is signed and logged. The Administrative Policy controls which actions the agent is allowed to perform. The Signing Policy controls which keys it can sign with and under what conditions.

This means:

* You can restrict an agent to a specific set of keys via security groups.
* You can freeze the agent's signing in one API call during an incident.
* Every action the agent takes appears in the audit log, attributed to that agent's identity.

The agent does not get any special bypass. It operates under the same trust model as any other identity in the vault.

## Example: signing a message from an agent

A minimal task once your agent has a Machine User identity (Ed25519 key + API key):

> "Using the Crypto Vault REST API, first call `GET /v1/whoami` to confirm you have signing permission, then sign the message `aGVsbG8=` with key `my-binance-key` via `POST /v1/keys/{key_id}/sign`. Sign each request using the Ed25519 transcript scheme from the OpenAPI spec."