~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
444 lines · 24.1 KB Raw History
# Commands: every method as an MCP tool and a CLI command

The server's methods are made for agents to call. An agent may call one over
XRPC, as a tool through the server's MCP endpoint, or as a command of the
`pds` CLI; each of the three is the same call, with the same arguments and
the same answer. The tools and the commands are not written one by one: they
are made from the lexicons in `lexicons/`, so a method the server serves is a
tool and a command as soon as it is served. The admin's two reads
(`OPERATIONS.md`, "The admin's reads"), the account's four routes for
its OAuth sessions (`OAUTH-ACCOUNT.md`) and its three for its passkeys
(`PASSKEYS.md`), which have no lexicon, are the exceptions: their tools
and commands are given below, in "The admin's reads", "The account's
OAuth sessions" and "The account's passkeys". This page says what they
are and how they are checked; `PDS.md` and the pages it links are the
rest of the server, and what they say still holds.

## One binary

The server and the CLI are one program, `pds`:

- `pds serve` runs the server, configured by the environment as `PDS.md`
  says. When it cannot start, as when its data does not recover, it exits 1
  with why on standard error.
- `pds migrate-blobs --to bucket|disk` moves the data directory's blobs
  into the bucket or out of it, given the same environment, while no
  server runs on it (`BLOBS.md`, "Moving them").
- `pds serve` and `pds migrate-blobs` each hold the data directory while
  they run: one started on a data directory another holds exits 1, with
  why on standard error, before it writes anything to standard output or
  changes anything in it. A process killed lets it go.
- `pds <group> <command> [flags]` calls a method of a running server, and
  `pds`, `pds --help` and `pds <group> --help` list the groups and commands,
  each with its lexicon's description.
- `pds xrpc <query|procedure> <name> [args]` calls any method or route of a
  running server by its name, as "Any call" says.

## Names

Each method the server serves has a group and a name, from its NSID: the
group is the NSID's second-to-last segment, and the name its last, as
written. `com.atproto.repo.createRecord` is group `repo`, name
`createRecord`. Then:

| As | Of `com.atproto.repo.createRecord` | Rule |
| --- | --- | --- |
| MCP tool | `repo_create_record` | group, `_`, name in snake case |
| MCP tool's `title` | `Create record (repo)` | the name in words, the first capitalized, then the group in parentheses |
| CLI command | `pds repo create-record` | group, then name in kebab case |
| CLI flag of `swapCommit` | `--swap-commit` | each parameter or input property, kebab case |
| Tool argument of `swapCommit` | `swapCommit` | as the lexicon names it |

The name in words is its kebab case with each `-` a space, so that
`com.atproto.identity.getRecommendedDidCredentials`' title is `Get
recommended did credentials (identity)`. No two methods the server serves
may share a group and name, and no group is `xrpc`.

## Which methods

Every method the server serves has a CLI command. Every one whose answer is
`application/json`, or that answers nothing, as `deleteSession`, has an MCP
tool: so all but those whose answer is a CAR file, `com.atproto.sync.getRepo`,
`getBlocks` and `getRecord`; `com.atproto.sync.getBlob`, whose answer is a
blob's bytes; and `com.atproto.sync.subscribeRepos`, which is a stream.
`subscribeRepos` has no CLI command either.

Nor has a method whose input is not JSON an MCP tool: `com.atproto.repo.uploadBlob`,
whose input is any bytes, and `com.atproto.repo.importRepo`, whose input is a
CAR file. With `com.atproto.sync.getBlob`, whose answer is the blob's bytes,
no MCP tool uploads or reads blobs, or imports a repository; their commands
do.

## The admin's reads

`/xrpc/_logs` and `/xrpc/_stats` (`OPERATIONS.md`, "The admin's reads") are
no lexicon's methods, so their tools and commands are written here rather
than made, and are otherwise as a method's: called with the same auth,
answering what the route answers, as "Answers" says, its errors as a
method's.

| Route | MCP tool | CLI command |
| --- | --- | --- |
| `_logs` | `admin_logs` | `pds admin logs` |
| `_stats` | `admin_stats` | `pds admin stats` |

They are in the group `admin`, after the commands of `com.atproto.admin`'s
methods, `logs` then `stats`, and listed after every lexicon's tool,
`admin_logs` then `admin_stats`. `admin_logs`'s arguments are
`_logs`'s parameters, `trace`, `msg`, `method`, `level`, `minMs` and
`limit`, none required, its `inputSchema`:

| Argument | Type | CLI flag |
| --- | --- | --- |
| `trace`, `msg`, `method` | `string` | `--trace`, `--msg`, `--method` |
| `level` | `string`, `enum` `debug`, `info`, `warn`, `error` | `--level` |
| `minMs` | `integer`, `minimum` 0 | `--min-ms` |
| `limit` | `integer`, `minimum` 1, `maximum` 500 | `--limit` |

`admin_stats` takes none: its `inputSchema` is an object with no
properties, and `pds admin stats` no flag. Both tools have `readOnlyHint:
true`, and a `title` by the rule of "Names", of their commands' names:
`Logs (admin)` and `Stats (admin)`. Their descriptions, the tools' and the
commands' in `--help`:

- `admin_logs`: "As the admin, the lines the server logged and kept in
  PDS_LOG_DIR, oldest first: the last of those of a trace, a message, a
  route, a level and above, or a time. Needs the admin's Basic auth."
- `admin_stats`: "As the admin, what the server counted since it started:
  its requests by route and status with their mean times, the requests it
  made, its syncs, its accounts and its firehose. Needs the admin's Basic
  auth."

## The account's OAuth sessions

`OAUTH-ACCOUNT.md`'s four routes are no lexicon's methods either, so their
tools and commands are written here, and are otherwise as a method's, as
the admin's reads are: called with the same auth, answering what the route
answers, its errors as a method's.

| Route | MCP tool | CLI command | Arguments |
| --- | --- | --- | --- |
| `_oauthSessions` | `oauth_sessions` | `pds oauth sessions` | none |
| `_oauthRevokeSession` | `oauth_revoke_session` | `pds oauth revoke-session` | `id` |
| `_oauthDevices` | `oauth_devices` | `pds oauth devices` | none |
| `_oauthRevokeDevice` | `oauth_revoke_device` | `pds oauth revoke-device` | `id` |

They are the group `oauth`, listed after every other group, its commands
in the order above, and their tools after the admin's reads, in the same
order. A tool with no arguments has an `inputSchema` that is an object with
no properties, and its command no flag; `id` is a `string`, required, the
flag `--id`. `oauth_sessions` and `oauth_devices` have `readOnlyHint:
true`; `oauth_revoke_session` and `oauth_revoke_device` `readOnlyHint:
false` and `destructiveHint: true`. Their titles are by the rule of
"Names", of their commands' names: `Sessions (oauth)`, `Revoke session
(oauth)`, `Devices (oauth)` and `Revoke device (oauth)`. Their
descriptions, the tools' and the commands' in `--help`:

- `oauth_sessions`: "The OAuth sessions of your account, the apps you
  signed in to, newest first: each with its id, client, issuer (atproto
  or mcp), scope, and when it started, was last refreshed and ends. Needs
  your account's password session."
- `oauth_revoke_session`: "End one of your account's OAuth sessions by its
  id, as oauth_sessions lists it: the app is signed out at once. Needs
  your account's password session."
- `oauth_devices`: "The browsers your account is signed in on through the
  OAuth sign-in page, newest sign-in first: each with its id, when it
  signed in, and its user agent and IP address. Needs your account's
  password session."
- `oauth_revoke_device`: "Sign your account out of one browser by its id,
  as oauth_devices lists it. Its apps' sessions stay: end those with
  oauth_revoke_session. Needs your account's password session."

## The account's passkeys

`PASSKEYS.md`'s three routes are no lexicon's methods either, and their
tools and commands are as those of "The account's OAuth sessions" are.

| Route | MCP tool | CLI command | Arguments |
| --- | --- | --- | --- |
| `_passkeyList` | `passkey_list` | `pds passkey list` | none |
| `_passkeyAdd` | `passkey_add` | `pds passkey add` | `name` |
| `_passkeyRemove` | `passkey_remove` | `pds passkey remove` | `id` |

They are the group `passkey`, listed after `oauth`, its commands in the
order above, and their tools after the `oauth_` tools, in the same order.
`passkey_list`'s `inputSchema` is an object with no properties, and its
command has no flag; `name` is a `string`, required, with `minLength` 1
and `maxLength` 64, the flag `--name`; `id` is a `string`, required, the
flag `--id`. `passkey_list` has `readOnlyHint: true`; `passkey_add`
`readOnlyHint: false` and `destructiveHint: false`; `passkey_remove`
`readOnlyHint: false` and `destructiveHint: true`. Their titles are by the
rule of "Names", of their commands' names: `List (passkey)`, `Add
(passkey)` and `Remove (passkey)`. Their descriptions, the tools' and the
commands' in `--help`:

- `passkey_list`: "The passkeys of your account, newest first: each with
  its id, name, when it was added and last signed in, and whether it is
  backed up. Needs your account's password session."
- `passkey_add`: "A link to open in a browser within 15 minutes, which
  adds a passkey of this name to your account: it then signs in on the
  OAuth sign-in page with no password. A new link ends the last. Needs
  your account's password session."
- `passkey_remove`: "Remove one of your account's passkeys by its id, as
  passkey_list lists it: it no longer signs in. Needs your account's
  password session."

## Arguments

A method's arguments are its lexicon's: a query's `parameters`, or a
procedure's `input` schema's properties. Where a required one names an
account, as `repo` and `did` do, it may be left out when a token is given,
and is then the token's account's DID: the server fills it in for a tool,
and the CLI asks the server with `getSession`. With no token, it is
required. An optional one, such as `createAccount`'s `did`, is never filled
in.

- **MCP.** A tool's `inputSchema` is a JSON Schema object whose properties
  are the method's arguments, each typed from its lexicon: `string`,
  `integer` and `boolean` as themselves, with `minimum`, `maximum`,
  `maxLength` and `enum` where the lexicon has them; `array` as `array`,
  with `maxItems` the lexicon's `maxLength` where it has one;
  `unknown`, `object`, `ref` and `union` as any JSON value of their kind
  (`object`, or no constraint for `unknown`), and `bytes`, `cid-link` and
  `blob` with no constraint, as `unknown`; an argument the lexicon lists
  as `nullable` has the type and `"null"`, as `["string", "null"]`; and its
  `required` the lexicon's, less `repo` and `did`. A tool's `description` is
  the lexicon's, its `title` as "Names" gives it, and its annotations as
  "Hints" says.
- **CLI.** Each argument is a flag. A `string` flag takes its text, an
  `integer` its digits, a `boolean` `true` or `false` (a bare boolean flag is
  `true`). Any other takes JSON: `--record '{"text":"hi"}'`, and `-` for its
  value reads the JSON from standard input. An argument cannot be given as
  `null` this way: one whose value is `null` is passed over XRPC or MCP. A
  flag the method does not take, a missing required one, or one that does
  not parse is a usage error: exit status 2, with what was wrong on standard
  error, and no call made.

## Hints

Each tool's `annotations` say what its call does, as MCP's tool
annotations do (`mcp/server/tools.md`): `readOnlyHint` whether it changes
nothing, and for one that changes something, `destructiveHint` whether it
may delete, replace or end what was there rather than only add. A client
may run a read-only tool without asking, and ask before a destructive one,
so they are given by what each method does, not by whether it is a query:

- A query has `readOnlyHint: true`, but for those that sign a token for
  the account, `com.atproto.server.getServiceAuth` and
  `com.atproto.space.getDelegationToken`: `readOnlyHint: false` and
  `destructiveHint: false`.
- A procedure has `readOnlyHint: false`, and `destructiveHint: false` if
  it only adds: `com.atproto.server.createAccount`, `createSession`,
  `createAppPassword`, `createInviteCode`, `createInviteCodes`,
  `requestEmailConfirmation`, `confirmEmail`, `requestEmailUpdate`,
  `requestPasswordReset`, `requestAccountDelete`, `activateAccount`;
  `com.atproto.identity.requestPlcOperationSignature`,
  `signPlcOperation`; `com.atproto.repo.createRecord`;
  `app.bsky.notification.registerPush`; and `com.atproto.space.createSpace`,
  `createRecord`, `authorizeSpaceSync` and `notifyRepoUpdate`. Every other
  procedure has `destructiveHint: true`: it may delete or replace a record,
  a repository, a space or its members, or end a session, an app password,
  a push registration or an account, or change its handle, email,
  password, preferences, status or DID document.

*Note:* a procedure is destructive unless this list names it, so one the
server comes to serve is asked about until it is added here.

## Auth

- **MCP.** `POST /mcp` takes `Authorization: Bearer <token>`, the same
  tokens XRPC takes, an MCP session's access token (`OAUTH-MCP.md`), or the
  admin's `Basic` (`LIMITS.md`), and passes it to the method as XRPC does:
  a tool answers a token the server did not give out, or no token, as its
  method answers it over XRPC, but where `OAUTH-MCP.md` answers an HTTP
  `401` challenge instead, so that a client signs in. Every tool is listed
  to every caller, with a token or without.
- **CLI.** `PDS_URL` is the server's base URL, and `PDS_TOKEN`, if set, its
  bearer token, sent as XRPC takes it. With `PDS_ADMIN_PASSWORD` set and
  `PDS_TOKEN` not, a command sends `Authorization: Basic` with the user
  `admin` and that password instead, as `createInviteCode` takes it
  (`LIMITS.md`). `pds server create-session
  --identifier … --password …` prints the session, whose `accessJwt` is a
  token.

The CLI's variables, then:

| Variable | Is |
| --- | --- |
| `PDS_URL` | the server's base URL |
| `PDS_TOKEN` | a bearer token to send, if set |
| `PDS_ADMIN_PASSWORD` | with no `PDS_TOKEN`, the admin's password, sent as `Basic` with the user `admin` |

## Answers

- **MCP.** A tool's answer is its method's JSON answer as
  `structuredContent`, with the same JSON in a `TextContent` block; for a
  method that answers nothing, as `deleteSession`, it is `{}`. An error
  the method answers is a tool execution error (`isError: true`) whose
  `structuredContent` is `{error, message}`, as XRPC names them; arguments
  the method refuses are such an error, as XRPC answers them. Only a tool
  not listed, or a `tools/call` that MCP's `CallToolRequest` schema refuses
  (no `name`, or `arguments` that is not an object), is the protocol error
  `-32602`.
- **CLI.** A command prints its method's JSON answer on standard output, one
  line, and exits 0; for a method that answers nothing, it prints `{}`. A
  command whose answer is a CAR file, as `get-repo`'s is, writes the file's
  bytes. An error the
  method answers is printed on standard output as `{status, error,
  message}`, with the HTTP status, and the command exits 1. A server that
  cannot be reached is exit status 3, with why on standard error.
  `get-blob` writes the blob's bytes, as `get-repo` does. `upload-blob`
  sends standard input as the body, with `--encoding` as its
  `Content-Type`; without `--encoding` it is a usage error. `import-repo`
  sends standard input as the body, as `application/vnd.ipld.car`, so that
  `pds sync get-repo --did <did> | pds repo import-repo` moves a
  repository between two servers, each its own `PDS_URL` and
  `PDS_TOKEN`.

## Any call

`pds xrpc <kind> <name> [args]` makes one XRPC call of the server at
`PDS_URL` by its name, with the auth of "Auth": a method the server
serves, one it forwards (`PROXY.md`), or one of its own routes, as
`_logs` or `_oauthSessions`. It is `goat xrpc`'s command, with its
arguments, but for its service, which is always `PDS_URL`; it knows no
lexicon, fills in nothing, and checks no argument against one, so the
server answers what is wrong with a call. It has no MCP tool.

| Argument | Is |
| --- | --- |
| `<kind>` | `query` (or `get`), a `GET`; `procedure` (or `post`), a `POST`; in any case |
| `<name>` | an NSID, or a route of the server's own, `_` then letters |
| `key==value` | a query parameter; given again, one more value of it |
| `key=value` | a string property of the JSON body |
| `key:=json` | a property of the JSON body, any JSON |
| `Name:value` | a request header; `Authorization` given so replaces the CLI's |
| `-` | the body, standard input as it comes, with the `Content-Type` a header gives |
| `@path` | a JSON object read from the file, its properties the body's before any given after it |

An argument is read at its first `:` or `=`: `==` makes a parameter,
`:=` a JSON property, a lone `=` a string property and a lone `:` a
header. A procedure's body is `-`'s, or otherwise the JSON object of its
properties, `{}` with none, as `application/json` unless a header names
another `Content-Type`; a query has none. A kind or name of another form
(an NSID as `atproto/nsid.md` defines one, or `_` and one or more
letters), an argument of none of these forms or with nothing before its
separator, a header name or value HTTP cannot carry, JSON that does not
parse, a body property, `@path` or `-` given to a query, `-` given twice
or beside body properties or `@path`, and an `@path` that cannot be read
or is not a JSON object are usage errors: exit status 2, with what was
wrong on standard error, and no call made. `--help` among the arguments
prints how it is called, exit 0, and makes no call.

It answers as a command does ("Answers"): a JSON answer printed on one
line, and an answer with no body `{}`, exit 0; an answer of another
`Content-Type` written as its bytes; an error printed as `{status, error,
message}`, exit 1; and a server that cannot be reached, exit 3.

```sh
pds xrpc query com.atproto.repo.listRecords repo==alice.test collection==app.bsky.feed.post limit==5
pds xrpc procedure com.atproto.repo.createRecord repo=alice.test collection=com.example.note 'record:={"text":"hi"}'
pds xrpc query _oauthSessions
pds xrpc procedure com.atproto.repo.uploadBlob Content-Type:image/png - < cat.png
pds xrpc query app.bsky.actor.getProfile actor==atproto.com Atproto-Accept-Labelers:did:plc:ar7c4by46qjdydhdevvrndac
```

## The MCP endpoint

`POST /mcp` on the server's port is a Streamable HTTP endpoint for MCP,
declaring only the `tools` capability. It is dual-era, as
`mcp/basic/versioning.md` names it ("Backward Compatibility with
Initialization-Based Versions"): it serves the modern revision
`2026-07-28` (`mcp/`) and the legacy revisions `2025-11-25` and
`2025-06-18` (`mcp/legacy/<version>/`), so that a client of either era
can use it. A request is served in the era it opens:

- **Modern.** A request whose `_meta` names a protocol version is served
  statelessly as `2026-07-28` says: `server/discover`, `tools/list` and
  `tools/call`, with no `initialize` and no session. What the endpoint
  checks of such a request, its method, headers, `Origin` and protocol
  version, and the errors it answers when they are wrong, are the
  transport's (`mcp/basic/transports/streamable-http.md`) and
  `mcp/basic/versioning.md`'s. A request with neither `_meta`'s version, a
  legacy `MCP-Protocol-Version`, nor the method `initialize` is held to the
  modern rules, and so refused: the server takes no client of `2025-03-26`,
  which sent no such header.
- **Legacy.** An `initialize` request, whatever its headers, is answered as
  `mcp/legacy/2025-11-25/basic/lifecycle.md` says: with the
  `protocolVersion` the client asked for if it is `2025-11-25` or
  `2025-06-18`, and `2025-11-25` otherwise; the capabilities `{tools:
  {}}`; `serverInfo` and `instructions` as `server/discover` gives them.
  The server assigns no session: it sends no `MCP-Session-Id`, and ignores
  one sent. Every later request names its version in the
  `MCP-Protocol-Version` header, and is served as that revision's
  transport (`basic/transports.md`) and `schema.json` say, statelessly:
  `ping` answers `{}`; `tools/list` and `tools/call` answer as in the
  modern era, the same tools, schemas and results, in that revision's
  shape; a notification, `notifications/initialized` among them, is `202
  Accepted` with no body; any other method is `-32601`. Each answer is
  HTTP `200`, its JSON-RPC error in it if any, but for what the transport
  makes an HTTP error: an `Origin` it refuses is `403`, and an
  `MCP-Protocol-Version` that names neither legacy revision nor
  `2026-07-28` is `400` with an `UnsupportedProtocolVersionError`.
- In either era, `GET` and `DELETE` on `/mcp` are `405 Method Not
  Allowed`: the server opens no stream of its own and keeps no session to
  end. `server/discover`'s `supportedVersions`, and the `supported` of
  every `UnsupportedProtocolVersionError`, are `2026-07-28`, `2025-11-25`
  and `2025-06-18`, in that order.

MCP's authorization, the OAuth sign-in of an MCP client and the bearer
token it calls the endpoint with, is `OAUTH-MCP.md`'s.

## How it is checked

`node compare.mjs --commands -- <pds> serve` sends some of its requests through
the MCP tool, the CLI command for the method, or `pds xrpc`, instead of
XRPC, and holds their answers to the reference's, as for XRPC; the MCP
answers and CLI output are turned back into status and JSON as above. A
tool call goes in either era, at random: modern, or legacy as `2025-11-25`
or `2025-06-18`. `pds xrpc` sends its arguments in each of their forms
that the request allows: parameters as `==`, properties as `=` or `:=` or
an `@path` file, a body as `-` where its input is not JSON. As well:

- `tools/list` must list exactly the tools above, named as above, and each
  tool's `inputSchema` must have exactly the lexicon's properties, typed as
  above, with the required ones above, `admin_logs` and `admin_stats`
  as "The admin's reads" gives them, the four `oauth_` tools as "The
  account's OAuth sessions" gives them, and the three `passkey_` tools as
  "The account's passkeys" gives them; each tool's `title` as "Names"
  gives it, and its `readOnlyHint` and `destructiveHint` as "Hints" gives
  them; in each legacy revision, the same
  tools as in the modern era. Every MCP message must be valid against the
  `schema.json` of its era's revision. `admin_logs` and `admin_stats`, and
  `pds admin logs` and `pds admin stats`, with the admin's auth, with a
  token, and with none, must answer as `_logs` and `_stats` do; each
  `oauth_` tool and its command, with an account's password token, an app
  password's, and none, as its route does (`OAUTH-ACCOUNT.md`, "How it is
  checked"); and each `passkey_` tool and its command likewise
  (`PASSKEYS.md`, "How it is checked").
- `pds xrpc` of each of the server's own routes, with the auth each
  takes, must answer as the route does; of a method the server forwards,
  as XRPC does; and each usage error above must exit 2, with no request
  reaching the server.
- `server/discover` must name the three versions. For each legacy
  revision, `initialize` with and without `MCP-Protocol-Version` must
  answer that revision, with the tools capability, the server's identity
  and instructions, and no `MCP-Session-Id`; asking for `2025-03-26` or a
  version no revision has must answer `2025-11-25`. Then
  `notifications/initialized` must be `202` with no body; `ping`, `{}`;
  `server/discover` with a legacy header, `-32601`; an unknown tool,
  `-32602`. A request with no version anywhere must be `400` with
  `-32020`, and an `MCP-Protocol-Version` of `2025-03-26`, `400` with
  `-32022` and the three versions. `GET` and `DELETE` on `/mcp` must be
  `405`.
- `pds <group> --help` must list exactly the group's commands, and `pds
  <group> <command> --help` its flags; a flag it does not take, and a
  command it does not have, must be usage errors.
- `node conformance.mjs -- <pds> serve` runs MCP's conformance suite against
  the endpoint, anonymously, for the scenarios that need none of the suite's
  own test tools: those of `2026-07-28`, and the legacy ones of `2025-11-25`
  (`server-initialize`, `server-session-lifecycle`, `ping`, `tools-list`
  and `dns-rebinding-protection`). `harness/conformance.yaml` names each
  check within them the server cannot pass by design, and why: those that
  need the suite's own tools, and the one for a server that does not
  implement `initialize`.