AT Protocol MCP Server

Appearance

API Reference ​

Complete API reference for the AT Protocol MCP Server, including all tools, resources, and types.

Overview ​

The AT Protocol MCP Server provides a comprehensive set of tools and resources for interacting with the AT Protocol ecosystem. This reference documentation covers:

  • Tools - 51 MCP tools for performing operations
  • Resources - 3 MCP resources plus 2 parameterized resource templates for accessing data
  • Prompts - 2 MCP prompts for guided content generation
  • Types - TypeScript type definitions

OAuth login is on the roadmap but not yet functional, so it is not exposed as a tool. Real-time firehose streaming is not planned as tools. See the Experimental & Roadmap page for details.

Tools ​

Tools are the primary way to interact with the AT Protocol through the MCP server. Each tool performs a specific operation and returns structured data.

Core Social Operations ​

Essential tools for social networking operations:

User Operations ​

Tools for managing user relationships and profiles:

Data Retrieval ​

Tools for searching and retrieving data:

Direct Messages ​

Tools for Bluesky direct messages (chat.bsky.convo, proxied to the Bluesky chat service). They require an app password created with "Allow access to your direct messages" enabled:

Bookmarks ​

Tools for private, account-scoped bookmarks (other users cannot see them):

Content Management ​

Tools for managing content and media:

Moderation ​

Tools for content and user moderation:

Advanced Social Features ​

Tools for advanced social networking:

Batch Operations ​

Tools for performing multiple operations at once:

  • batch_action - Apply one action (follow, like, or repost) across up to 25 targets in a single call

Analytics & Insights ​

Tools for analyzing engagement and network patterns:

  • analyze_account - Analyze a single account along one dimension (engagement, network, or strategy); engagement rate is engagement per hour since posting, not per follower
  • find_influential_users - Find influential users in a topic area

Content Discovery ​

Tools for discovering content and users:

  • discover - Surface timeline content via mode: 'trending' | 'recommended', sampling the caller's own home timeline (not network-wide)
  • find_similar_users - Find users similar to a given user via shared follows/followers (graph-only; not content/topic similarity)
  • discover_communities - Discover communities around topics
  • search_starter_packs - Search Bluesky starter packs by keyword (works without authentication)
  • get_starter_pack - Fetch a starter pack's details by AT-URI or bsky.app link (works without authentication)

Composite Operations ​

Tools that combine multiple operations:

  • get_user_summary - Get complete user profile with stats and analysis
  • get_post_context - Get a post with thread, author, engagement, and media data (replaces the former get_thread and extract_media_from_post)

Rich Media ​

Tools for working with images and media:

  • analyze_image - Report an image blob's declared size and MIME type (does not decode pixels, so no dimensions or aspect ratio)

Resources ​

The server exposes 3 static resources that provide read-only access to the authenticated user's AT Protocol data through the MCP protocol:

  • Timeline Resource - Current user's timeline feed (requires authentication; calls the real API)
  • Profile Resource - Current user's profile information (requires authentication; calls the real API)
  • Notifications Resource - Current user's notifications (requires authentication; calls the real API)

It also advertises 2 parameterized resource templates (resources/templates/list) that expose any actor's public data and work without authentication (they fall back to the public API when no session is active):

  • atproto://profile/{actor} - Public profile and statistics for any actor, addressed by handle (e.g. alice.bsky.social) or DID
  • atproto://feed/{actor} - Recent public posts by any actor

The {actor} variable supports completion/complete (the server offers the authenticated user's own handle as a candidate).

The placeholder Conversation Context resource (atproto://conversation-context) from earlier releases has been removed — it was never auto-populated and could only return empty content. Reading a URI that matches neither a static resource nor a template returns JSON-RPC error -32002 (Resource not found).

Prompts ​

The server provides 2 prompts for guided content generation. They are pure text templates and work without authentication:

  • content_composition - Compose a post from a topic. Arguments: topic, tone, length, include_hashtags.
  • reply_template - Draft a contextual reply. Arguments: original_post, reply_type, relationship.

Prompt arguments support completion/complete: enumerable arguments (such as tone or reply_type) return candidate values, while free-text arguments complete to an empty list.

Types ​

TypeScript type definitions used throughout the server:

Authentication ​

Most tools require authentication.

App Passwords (Supported) ​

App passwords are the supported authentication path. Generate an app password in your Bluesky Settings → Privacy and security → App passwords, then set:

bash
export ATPROTO_IDENTIFIER="your-handle.bsky.social"
export ATPROTO_PASSWORD="your-app-password"

OAuth (Planned) ​

OAuth login is on the roadmap but not yet functional, so it is not exposed as a configuration path or a tool. Use app passwords (above) for authentication. See the Authentication Guide and Experimental & Roadmap.

Unauthenticated Mode ​

The server runs without credentials, but only public/enhanced tools work. In practice this is limited to:

  • get_user_profile / get_user_summary - Public profile lookup (returns additional viewer-specific data when authenticated)
  • search_actors - Find accounts by handle or display name
  • get_author_feed - List a user's posts
  • get_user_connections - Follower/following lists (ENHANCED mode: works without auth, enriches the underlying API call when authenticated)
  • search_starter_packs / get_starter_pack - Starter pack search and lookup
  • get_post_context, analyze_image, and other PUBLIC/ENHANCED rich-media and composite tools

All other tools — including search_posts, get_timeline, and get_custom_feed — require authentication. (search_posts previously worked unauthenticated, but the AT Protocol search API changed in 2025 to require auth.)

Error Handling ​

All tools follow consistent error handling patterns. See the Error Handling Guide for details.

Rate Limiting ​

The server applies a per-tool rate limit of 100 requests per minute. Requests that exceed the limit for a given tool are rejected until the window resets. See the Configuration Guide for details.

Examples ​

For practical examples of using these tools, see:

Support ​