~ knotless Search/
↑↓ move↵ open⇧↵ all results
0
0
144 lines · 6.1 KB Raw History

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:

VariableWhat it does
PDS_URLThe server's base URL.
PDS_TOKENA bearer token to send, if it's set.
PDS_ADMIN_PASSWORDWhen 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:

  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 describes.