Architecture & Diagrams
Visual representations of the AT Protocol MCP Server architecture and the interaction sequences behind common operations.
Transport
By default the server communicates with MCP clients over stdio (StdioServerTransport), binding no network port. With --transport http it serves the MCP Streamable HTTP transport at /mcp instead (loopback by default). Outbound calls to the AT Protocol use HTTPS either way. The diagrams below show the default stdio setup.
System Architecture
The server sits between an MCP client and the AT Protocol. Tools and resources call the AT Protocol over HTTPS (the PDS for record writes, the App View for read/aggregation queries).
Streaming is not wired into this diagram
There are no streaming tools — the non-functional firehose/streaming tools were removed in 0.4.0, and firehose frame decoding is not implemented, so the server opens no WebSocket and surfaces no live events. See Experimental & Roadmap.
Request Data Flow
Every tool invocation is rate limited per tool (100 requests per minute per tool) before it runs. Most tools require an authenticated session; a few public/enhanced tools (such as get_user_profile, get_user_connections, and get_author_feed) run unauthenticated. search_posts is not one of them — it requires authentication, since the AT Protocol search API changed in 2025 to require auth.
Results are JSON text
Tool results are returned as stringified JSON text content, not a guaranteed structured schema.
Tool Organization
A representative slice of the 51 tools, grouped by area. (The former streaming and OAuth tools were removed in 0.4.0 because they never worked — see Experimental & Roadmap.)
Resources
The server registers 3 resources. All of them fetch live data from the AT Protocol and require authentication.
Removed placeholder
The atproto://conversation-context placeholder resource from earlier releases has been removed — it was never auto-populated and could only read as empty. See Experimental & Roadmap.
Post Creation Flow
Search and Pagination
search_posts returns a page of results plus an optional cursor; passing the cursor back fetches the next page until no cursor is returned.
Image Upload and Embed
Upload returns a blob reference; pass it into create_post to embed the image.
Follow / Unfollow
follow_user returns the follow record's URI; pass it to unfollow_user to remove the follow.
Profile Update
Moderation
Reports are submitted via com.atproto.moderation.createReport. Blocking and muting write the corresponding records.
Resource Access
Resources fetch directly from the AT Protocol on each read; there is no caching layer.
Error Handling
A rate-limited request from the AT Protocol surfaces to the client as a rate-limit error; the client decides whether and when to retry.