Skip to content

MCP Protocol

Understanding the Model Context Protocol and how it works with the AT Protocol MCP Server.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). It enables LLMs to securely access data and tools from external systems.

Key Concepts

MCP defines three main primitives:

  1. Tools - Functions that LLMs can execute
  2. Resources - Data sources that LLMs can read
  3. Prompts - Templates for common tasks

Architecture

┌─────────────────────────────────────┐
│         LLM Client                  │
│  (Claude, GPT, etc.)                │
└──────────────┬──────────────────────┘

               │ JSON-RPC 2.0
               │ over stdio/HTTP

┌──────────────▼──────────────────────┐
│      MCP Server                     │
│  ┌──────────────────────────────┐  │
│  │  Tools                       │  │
│  │  - create_post               │  │
│  │  - search_posts              │  │
│  │  - follow_user               │  │
│  └──────────────────────────────┘  │
│  ┌──────────────────────────────┐  │
│  │  Resources                   │  │
│  │  - atproto://timeline        │  │
│  │  - atproto://profile         │  │
│  └──────────────────────────────┘  │
│  ┌──────────────────────────────┐  │
│  │  Prompts                     │  │
│  │  - content_composition       │  │
│  │  - reply_template            │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘

MCP Tools

Tools are executable functions that LLMs can call to perform actions.

Tool Structure

Each tool has:

typescript
{
  name: string;           // Unique identifier
  description: string;    // What the tool does
  inputSchema: {          // Zod schema for parameters
    type: "object",
    properties: { ... },
    required: [ ... ]
  }
}

Example Tool

typescript
{
  name: "create_post",
  description: "Create a new post on AT Protocol",
  inputSchema: {
    type: "object",
    properties: {
      text: {
        type: "string",
        description: "Post content (max 300 characters)"
      },
      langs: {
        type: "array",
        items: { type: "string" },
        description: "Language codes (e.g., ['en', 'es'])"
      }
    },
    required: ["text"]
  }
}

Tool Execution Flow

1. LLM decides to use a tool

2. LLM sends tool call request
   {
     "method": "tools/call",
     "params": {
       "name": "create_post",
       "arguments": { "text": "Hello world!" }
     }
   }

3. Server validates parameters

4. Server executes tool

5. Server returns result
   {
     "content": [{
       "type": "text",
       "text": "Post created successfully"
     }]
   }

Available Tools

The AT Protocol MCP Server provides 30+ tools across categories:

  • Social Operations: create_post, like_post, repost, follow_user
  • Data Retrieval: search_posts, get_user_profile, get_timeline
  • Content Management: delete_post, update_profile, upload_image
  • Moderation: mute_user, block_user, report_content
  • OAuth: start_oauth_flow, refresh_oauth_tokens
  • Streaming: start_streaming, get_recent_events

See API Reference for complete list.

MCP Resources

Resources are data sources that LLMs can read to get context.

Resource Structure

typescript
{
  uri: string;           // Unique resource identifier
  name: string;          // Human-readable name
  description: string;   // What data it provides
  mimeType: string;      // Content type
}

Example Resource

typescript
{
  uri: "atproto://timeline",
  name: "User Timeline",
  description: "Current user's timeline feed with recent posts",
  mimeType: "application/json"
}

Resource Access Flow

1. LLM requests resource list
   {
     "method": "resources/list"
   }

2. Server returns available resources
   {
     "resources": [
       { "uri": "atproto://timeline", ... },
       { "uri": "atproto://profile", ... }
     ]
   }

3. LLM reads specific resource
   {
     "method": "resources/read",
     "params": { "uri": "atproto://timeline" }
   }

4. Server returns resource content
   {
     "contents": [{
       "uri": "atproto://timeline",
       "mimeType": "application/json",
       "text": "{ ... timeline data ... }"
     }]
   }

Available Resources

  • atproto://timeline - User's personalized timeline
  • atproto://profile - User's profile information
  • atproto://notifications - Recent notifications

See API Reference for details.

MCP Prompts

Prompts are templates that help LLMs perform common tasks.

Prompt Structure

typescript
{
  name: string;          // Unique identifier
  description: string;   // What the prompt helps with
  arguments: [{          // Optional parameters
    name: string;
    description: string;
    required: boolean;
  }]
}

Example Prompt

typescript
{
  name: "content_composition",
  description: "Help compose engaging social media posts",
  arguments: [
    {
      name: "topic",
      description: "Topic to write about",
      required: false
    },
    {
      name: "tone",
      description: "Desired tone (casual, professional, humorous)",
      required: false
    }
  ]
}

Prompt Usage Flow

1. LLM requests prompt list
   {
     "method": "prompts/list"
   }

2. Server returns available prompts
   {
     "prompts": [
       { "name": "content_composition", ... }
     ]
   }

3. LLM gets prompt with arguments
   {
     "method": "prompts/get",
     "params": {
       "name": "content_composition",
       "arguments": {
         "topic": "AI",
         "tone": "casual"
       }
     }
   }

4. Server returns prompt messages
   {
     "messages": [{
       "role": "user",
       "content": {
         "type": "text",
         "text": "Create a casual post about AI..."
       }
     }]
   }

Available Prompts

  • content_composition - Help write engaging posts
  • reply_template - Generate thoughtful replies

See API Reference for details.

Transport Protocols

The AT Protocol MCP Server uses the stdio (Standard Input/Output) transport mechanism for local integrations:

bash
atproto-mcp

Communication occurs via stdin/stdout using JSON-RPC 2.0, which is the standard transport for MCP servers integrated with LLM clients like Claude Desktop.

Note: HTTP/SSE transport is not currently implemented. The stdio transport is recommended for all MCP server integrations as it provides secure, local communication between the LLM client and the server.

Message Format

All MCP messages use JSON-RPC 2.0:

Request

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_post",
    "arguments": {
      "text": "Hello from MCP!"
    }
  }
}

Response (Success)

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "Post created successfully"
    }]
  }
}

Response (Error)

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "details": "Authentication required"
    }
  }
}

Error Codes

Standard JSON-RPC 2.0 error codes:

CodeMeaningDescription
-32700Parse errorInvalid JSON
-32600Invalid requestInvalid JSON-RPC
-32601Method not foundUnknown method
-32602Invalid paramsInvalid parameters
-32603Internal errorServer error

Capabilities

The server advertises its capabilities:

json
{
  "capabilities": {
    "tools": {
      "listChanged": true
    },
    "resources": {
      "subscribe": false,
      "listChanged": true
    },
    "prompts": {
      "listChanged": true
    }
  }
}

Best Practices

For Tool Design

  • ✅ Use clear, descriptive names
  • ✅ Provide detailed descriptions
  • ✅ Validate all inputs with Zod schemas
  • ✅ Return structured, consistent results
  • ✅ Handle errors gracefully

For Resource Design

  • ✅ Use meaningful URI schemes
  • ✅ Return well-structured data
  • ✅ Include timestamps
  • ✅ Implement proper caching
  • ✅ Handle large datasets efficiently

For Prompt Design

  • ✅ Make prompts reusable
  • ✅ Support customization via arguments
  • ✅ Provide clear guidance
  • ✅ Include examples
  • ✅ Consider context length

Next Steps


Previous: Authentication ← | Next: AT Protocol

Released under the MIT License.