chadtmiller.com/monolith
An atproto PDS
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). 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:
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:
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,
Operating).
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). An app password or an OAuth token can't do this. These commands do what the reference's account pages do:
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). 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:
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). 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):
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). 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:
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). 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). 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).
The server's root page, GET /, says how:
- Add
<your server's URL>/mcpto the app as a connector. In Claude, go to Settings > Connectors > Add custom connector, and choose "Sign in when needed". - When it asks, sign in on the server's page and approve it.
- 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 describes.