chadtmiller.com/monolith
An atproto PDS
0
0
# Calling the server
You can call every method the server serves in three ways: over XRPC, as a
command of the `pds` CLI, and as a tool on its MCP endpoint. All three
take the same arguments and give the same answer.
## Names
The tool and the command names come from the method's lexicon
([COMMANDS.md](../../spec/COMMANDS.md#names)). For example,
`com.atproto.repo.createRecord` is the tool `repo_create_record` and the
command `pds repo create-record`. Its arguments are the tool's arguments,
or the command's flags. So a method added to the server becomes a tool and
a command at once.
When a method names an account (`repo`, for example), the tool and the
command can leave it out, and then it's the token's account.
## XRPC
The methods are under `/xrpc/`, like on any atproto PDS:
```sh
curl https://pds.example.com/xrpc/com.atproto.server.describeServer
```
## The CLI
`pds <group> <command> [flags]` calls a running server. It reads three
variables:
| Variable | What it does |
| --- | --- |
| `PDS_URL` | The server's base URL. |
| `PDS_TOKEN` | A bearer token to send, if it's set. |
| `PDS_ADMIN_PASSWORD` | When there's no `PDS_TOKEN`, the admin's password, sent as `Basic` with the user `admin`. |
Sign in, keep the access token, and call:
```sh
export PDS_URL=https://pds.example.com
export PDS_TOKEN=$(pds server create-session --identifier alice.pds.example.com --password … | jq -r .accessJwt)
pds repo create-record --collection com.example.note --record '{"text":"hi"}'
pds repo list-records --collection com.example.note --limit 5
```
`pds --help` lists the groups and commands, and `pds <group> --help` lists
a group's, each with its lexicon's description. `pds admin logs` and `pds
admin stats` (and the MCP tools `admin_logs` and `admin_stats`) are how
the admin reads the log and the metrics, which have no lexicon
([COMMANDS.md](../../spec/COMMANDS.md#the-admins-reads),
[Operating](operating.md#reading-the-log-and-stats)).
An account lists and ends its OAuth sessions (the apps it signed in to)
and the browsers it's signed in on with its own password session
([OAUTH-ACCOUNT.md](../../spec/OAUTH-ACCOUNT.md)). An app password or an
OAuth token can't do this. These commands do what the reference's account
pages do:
```sh
pds oauth sessions # each session's id, client, scope
pds oauth revoke-session --id <id> # sign that app out
pds oauth devices # each browser's id, user agent, IP
pds oauth revoke-device --id <id> # sign the account out of it
```
The matching MCP tools are `oauth_sessions`, `oauth_revoke_session`,
`oauth_devices` and `oauth_revoke_device`.
You add, list and remove passkeys the same way, with the password session
([PASSKEYS.md](../../spec/PASSKEYS.md)). `pds passkey add` answers with a
link that's good for 15 minutes. Open it in a browser on the device that'll
hold the passkey. After that, the account signs in on the authorization
page with `Sign in with a passkey`, with no password and no email code:
```sh
pds passkey add --name Laptop # {"url": ".../oauth/passkey?token=…", "expiresAt": …}
pds passkey list # each passkey's id, name, when added and last used
pds passkey remove --id <id> # it no longer signs in
```
The matching MCP tools are `passkey_list`, `passkey_add` and
`passkey_remove`. Treat the link as a secret, since whoever opens it in
time adds a passkey to the account.
A few commands send or write bytes instead of JSON
([COMMANDS.md](../../spec/COMMANDS.md#answers)). `sync get-repo` and
`sync get-blob` write the CAR file or blob to standard output.
`repo upload-blob --encoding <type>` sends standard input as the blob, and
`repo import-repo` sends standard input as a CAR file. That means you can
move a repository from one server to another when the account moves, each
side with its own `PDS_URL` and `PDS_TOKEN`
([MIGRATION.md](../../spec/MIGRATION.md)):
```sh
PDS_URL=$OLD PDS_TOKEN=$OLD_TOKEN pds sync get-repo --did "$DID" \
| PDS_URL=$NEW PDS_TOKEN=$NEW_TOKEN pds repo import-repo
```
`pds xrpc` makes any call by name, with `goat xrpc`'s arguments
([COMMANDS.md](../../spec/COMMANDS.md#any-call)). `k==v` is a query
parameter, `k=v` a string property of the body, `k:=json` any other
property, `Name:value` a header, and `-` sends standard input as the body.
It reaches methods that have no command, such as one the server forwards
to the AppView, and it checks nothing before sending:
```sh
pds xrpc query app.bsky.actor.getProfile actor==atproto.com
pds xrpc procedure com.atproto.repo.createRecord repo=alice.test collection=com.example.note 'record:={"text":"hi"}'
```
## MCP
`POST /mcp` is an MCP endpoint over Streamable HTTP, and it serves only
tools ([COMMANDS.md](../../spec/COMMANDS.md#the-mcp-endpoint)). It serves
clients of either era of MCP. That's the stateless revision `2026-07-28`
and, after an `initialize`, the legacy `2025-11-25` and `2025-06-18` that
most clients still speak.
It takes `Authorization: Bearer <token>` with any token XRPC takes or an
MCP client's OAuth access token. It also takes the admin's `Basic`. Every
caller sees every tool listed, with a token or without.
Each tool has a `title`, and its annotations say what it does
([COMMANDS.md](../../spec/COMMANDS.md#hints)). A read is `readOnlyHint`,
and a call that may delete, replace or end something is `destructiveHint`.
So a client asks before those, but not before a read or a new record.
## Connect an AI app
An MCP client such as Claude signs in by OAuth, the way MCP's
authorization spec describes ([OAUTH-MCP.md](../../spec/OAUTH-MCP.md)).
The server's root page, `GET /`, says how:
1. Add `<your server's URL>/mcp` to the app as a connector. In Claude, go
to Settings > Connectors > Add custom connector, and choose "Sign in
when needed".
2. When it asks, sign in on the server's page and approve it.
3. Ask it things, like "What have I posted this week?"
The client finds the server's MCP issuer from the endpoint's metadata, and
the token it gets is only for `/mcp`. Claude can only reach a server on the
internet, so you'll need a server deployed the way
[Deploying](deploying.md) describes.