Skip to main content
pdsx includes an MCP (model context protocol) server that exposes atproto record operations to AI agents like Claude Code, Cursor, and other MCP-compatible clients.

hosted instance

the easiest way to get started - no installation required:
this gives your AI agent access to read public atproto data immediately.

adding authentication

for write operations (create, update, delete), add your credentials:
use an app password, not your account password. app passwords can be revoked individually if compromised.

custom PDS

nothing extra to configure. pdsx resolves your account’s PDS from your handle’s DID document, so a self-hosted account authenticates with the same two headers as everyone else.
this used to require an x-atproto-pds-url header. it no longer does — authenticated calls previously defaulted to bsky.social, which mints a token your own PDS rejects with BadJwtSignature. the PDS is now discovered from your handle.
x-atproto-pds-url still exists as an override, for pointing at a host that differs from what your DID document names:
reading public data from another account never needs configuration — pdsx discovers their PDS too.

local/self-hosted

run the MCP server locally for development or self-hosting:
or use uvx without installing:

configure claude code for local server

with authentication via environment:

available tools

the MCP server exposes nine tools:
permissioned data (pdsx spaces …) is CLI only — there are no MCP tools for com.atproto.space.* while the proposal is still experimental.

read operations

read operations work without authentication when you specify a repo:
without a repo parameter, the server reads from your authenticated account. get_record preserves the full record value, including facet byte ranges, $type, language tags, and reply CIDs. list_records returns compact values: facets become links/mentions, reply references become URI strings, and nulls, $type, and English-only language tags are omitted. Use get_record when inspecting the stored schema or preparing an edit. list_records returns {results: [...], cursor: ...} with or without select. Pass the returned cursor unchanged to read the next page; null marks the end of a successful traversal. A jq filter can return no matches while the cursor still points to another page. Pages exceeding the response size limit return error: "response_too_large" and retry_cursor instead of partial results. Reduce limit or narrow select and retry with that cursor. No continuation cursor is returned for an oversized page, so unseen records cannot be silently skipped by advancing past it. The MCP read tools simplify record values. In post records, value.reply.parent and value.reply.root are URI strings, not the original {uri, cid} objects.

write operations

write operations always require authentication:

PDS discovery

pdsx automatically discovers the correct PDS for any user. when you query records from repo="zzstoatzz.io", it:
  1. resolves the handle to a DID
  2. looks up the DID document
  3. extracts the PDS endpoint
  4. queries that PDS directly
this means you can read records from users on any PDS - including self-hosted instances - without any configuration.

common collections

here are the most commonly used collections:

prompts

the MCP server includes built-in prompts for guidance:
  • usage_guide - general usage instructions
  • create_post_guide - how to create posts with rich text

resources

the server exposes one resource:
  • pdsx://me - shows your authenticated identity (handle and DID)

example workflows

reading someone’s recent posts

getting a user’s bio

creating a post

updating your bio

troubleshooting

”authentication required”

you’re trying to perform an operation that needs credentials:
  • write operations (create, update, delete) always need auth
  • read operations without repo parameter need auth
add credentials via headers (hosted) or environment variables (local).

empty results for custom PDS users

if you’re getting empty results when querying a user on a self-hosted PDS, ensure you’re using a recent version of pdsx. older versions didn’t automatically discover custom PDS endpoints.

”could not find repo”

the handle or DID couldn’t be resolved. check:
  • the handle is spelled correctly
  • the account exists and isn’t deleted
  • your network can reach the PDS

what’s next