---
title: "For AI agents"
description: "Find Anlyon's machine-readable docs, the API's OpenAPI spec and the MCP endpoint, and authenticate an agent to the Anlyon API."
sidebar:
  label: For AI agents
---

This page is for AI agents and the people who set them up. It lists where the machine-readable sources are, so an agent can read the docs, call the API and connect over MCP without scraping HTML or guessing endpoints.

## Read the docs as Markdown

Start with the smallest source that answers the question.

| Need | URL |
| --- | --- |
| Every page, with a one-line summary, in sidebar order | [`https://docs.anlyon.com/llms.txt`](https://docs.anlyon.com/llms.txt) |
| One page without site navigation | Append `.md` to its URL, for example [`https://docs.anlyon.com/quickstart.md`](https://docs.anlyon.com/quickstart.md). `.mdx` returns the source with components as written. |
| Every page's Markdown in one file | [`https://docs.anlyon.com/llms-full.txt`](https://docs.anlyon.com/llms-full.txt) |
| Pages with their Markdown and JSON URLs | [`https://docs.anlyon.com/api/docs/pages.json`](https://docs.anlyon.com/api/docs/pages.json) |
| Every agent-facing file on this site | [`https://docs.anlyon.com/agent-readability.json`](https://docs.anlyon.com/agent-readability.json) |

The site also publishes an [API catalog](https://docs.anlyon.com/.well-known/api-catalog) and an [AI catalog](https://docs.anlyon.com/.well-known/ai-catalog.json). The documentation is served as static files: there is no live documentation search endpoint and no documentation MCP server.

Read in this order for most tasks: [Why Anlyon](/why-anlyon.md), the [quickstart](/quickstart.md), [Act for your users](/guides/act-for-your-users.md), then the page for the framework or client you are wiring up.

## Fetch the API's OpenAPI spec

| What | URL |
| --- | --- |
| The Anlyon API's OpenAPI document | [`https://docs.anlyon.com/api-reference/openapi.json`](https://docs.anlyon.com/api-reference/openapi.json) |
| The same operations, one page each | [`https://docs.anlyon.com/api-reference`](/api-reference) |
| The API's base URL | `https://api.anlyon.com`. Every operation is under `/api/v2`. |

Take exact paths, parameters, request bodies, scopes and response schemas from the spec, not from examples. Each operation lists the scope it needs in `x-anlyon-scopes`.

`https://docs.anlyon.com/openapi.json` is a different document: it describes this documentation site's own JSON API, not the Anlyon API.

## Connect to the Anlyon MCP server

| What | URL |
| --- | --- |
| Every action in the workspace, plus approval tools | `https://api.anlyon.com/mcp` |
| One integration's actions, plus approval tools | `https://api.anlyon.com/mcp/<integration>`, for example `https://api.anlyon.com/mcp/github` |

The server speaks Streamable HTTP. Its tools include `list_actions`, `invoke_action`, `check_approval` and `wait_for_approval`, and each enabled action also appears as its own tool, `action_<name>`, with the action's input schema. See [MCP servers](/agents/mcp-servers) for every tool and [Claude Code](/agents/claude-code), [Cursor](/agents/cursor) or [Codex](/agents/codex) for exact client configuration.

## Authenticate an agent

Pick one of these. An agent never needs, and never receives, a provider credential such as a GitHub or Gmail token: Anlyon adds it when it makes the call.

- **OAuth, for an MCP client a person uses.** Point the client at `https://api.anlyon.com/mcp`. It registers itself and opens a browser, where the person signs in and chooses the workspace, the environment and the permission groups. **Approve on your behalf**, secrets, budgets and notification channels are off unless they turn them on.
- **An API key, for the REST API or a server-side MCP connection.** Send `Authorization: Bearer anlyon_live_...`. A key belongs to one environment and holds a fixed set of scopes. An agent key needs `actions:read`, `actions:invoke` and `approvals:read`, and nothing privileged. Create it in **Settings → API Keys** in the [console](https://console.anlyon.com). See [API keys and scopes](/authentication).
- **Acting for one of a product's users.** The product's server, not the model, adds `Anlyon-End-User: <id>` to each request made with an API key (`anlyon.forUser(id)` in TypeScript, `client.for_user(id)` in Python, `--end-user <id>` for the stdio MCP server). An OAuth connection that sends this header is refused with `END_USER_HEADER_NOT_ALLOWED`. See [Workspace and end-user connections](/execution/end-user-connections).

Check a key before doing work: `GET https://api.anlyon.com/api/v2/auth/identity` returns its environment, scopes and expiry and never a secret.

```bash
curl https://api.anlyon.com/api/v2/auth/identity \
  -H "Authorization: Bearer $ANLYON_API_KEY"
```

## Follow the rules an agent should keep

- **Never retry an `unknown` outcome.** It may have reached the provider. Read the receipt, or tell a person. See [When the outcome is unknown](/execution/when-the-outcome-is-unknown).
- **Wait for a pending approval instead of calling again.** A second call is a second request for approval. Use `wait_for_approval`, or check the invocation later.
- **Treat a refusal as final.** `grade: "refused"` (a limit), `denied` (a person or a policy said no) and `failed` before dispatch mean nothing was sent. Report it; do not work around it.
- **On `connect_required`, ask the user to connect.** The result carries a `connectUrl`. Nothing was done.

## Set up a project with one prompt

The [agent setup prompt](/agents/prompt) walks a coding agent through installing the SDK, creating the right keys and wiring the first action call, using only these docs.