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.
The tool and the command names come from the method’s lexicon
(Commands: every method as an MCP tool and a CLI command). 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.
The methods are under /xrpc/, like on any atproto PDS:
curl https://pds.example.com/xrpc/com.atproto.server.describeServerThe CLI
Section titled “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.comexport 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 5pds --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: every method as an MCP tool and a CLI command,
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: the account's own sessions and devices). 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, scopepds oauth revoke-session --id <id> # sign that app outpds oauth devices # each browser's id, user agent, IPpds oauth revoke-device --id <id> # sign the account out of itThe 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). 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 usedpds passkey remove --id <id> # it no longer signs inThe 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: every method as an MCP tool and a CLI command). 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
(Moving an account between servers):
PDS_URL=$OLD PDS_TOKEN=$OLD_TOKEN pds sync get-repo --did "$DID" \ | PDS_URL=$NEW PDS_TOKEN=$NEW_TOKEN pds repo import-repopds xrpc makes any call by name, with goat xrpc’s arguments
(Commands: every method as an MCP tool and a CLI command). 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.compds xrpc procedure com.atproto.repo.createRecord repo=alice.test collection=com.example.note 'record:={"text":"hi"}'POST /mcp is an MCP endpoint over Streamable HTTP, and it serves only
tools (Commands: every method as an MCP tool and a CLI command). 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: every method as an MCP tool and a CLI command). 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
Section titled “Connect an AI app”An MCP client such as Claude signs in by OAuth, the way MCP’s
authorization spec describes (OAuth for MCP clients).
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.