Skip to content

API Reference

Jump to bottom
Cameron Rye edited this page Nov 16, 2025 · 1 revision

API Reference

Complete API reference for the ActivityPub MCP Server.

MCP Resources

Resources provide read-only access to fediverse data. See MCP Resources for detailed documentation.

server-info

activitypub://server-info

Get information about the MCP server.

remote-actor

activitypub://remote-actor/{identifier}

Get information about any actor in the fediverse.

Parameters:

  • identifier: Actor's fediverse handle (e.g., user@mastodon.social)

remote-timeline

activitypub://remote-timeline/{identifier}

Access any actor's timeline/outbox.

Parameters:

  • identifier: Actor's fediverse handle

instance-info

activitypub://instance-info/{domain}

Get information about any fediverse instance.

Parameters:

  • domain: Instance domain (e.g., mastodon.social)

remote-followers

activitypub://remote-followers/{identifier}

Get the followers list of any actor.

Parameters:

  • identifier: Actor's fediverse handle

remote-following

activitypub://remote-following/{identifier}

Get the following list of any actor.

Parameters:

  • identifier: Actor's fediverse handle

MCP Tools

Tools enable interactive operations. See MCP Tools for detailed documentation.

discover-actor

Discover and get information about any actor.

Input Schema:

{
  identifier: string  // Actor's fediverse handle
}

Example:

{
  "name": "discover-actor",
  "arguments": {
    "identifier": "Gargron@mastodon.social"
  }
}

fetch-timeline

Fetch recent posts from any actor's timeline.

Input Schema:

{
  identifier: string  // Actor's fediverse handle
  limit?: number      // Number of posts (1-50, default: 20)
}

Example:

{
  "name": "fetch-timeline",
  "arguments": {
    "identifier": "Gargron@mastodon.social",
    "limit": 10
  }
}

get-instance-info

Get detailed information about any fediverse instance.

Input Schema:

{
  domain: string  // Instance domain
}

Example:

{
  "name": "get-instance-info",
  "arguments": {
    "domain": "mastodon.social"
  }
}

search-instance

Search for content on a specific instance.

Input Schema:

{
  domain: string       // Instance domain
  query: string        // Search query
  type?: string        // "accounts" | "statuses" | "hashtags"
}

Example:

{
  "name": "search-instance",
  "arguments": {
    "domain": "mastodon.social",
    "query": "typescript",
    "type": "accounts"
  }
}

discover-instances

Find popular fediverse instances.

Input Schema:

{
  category?: string          // "mastodon" | "pleroma" | "misskey" | etc.
  topic?: string             // Topic or interest
  size?: string              // "small" | "medium" | "large"
  region?: string            // Geographic region or language
  beginnerFriendly?: boolean // Show only beginner-friendly
}

Example:

{
  "name": "discover-instances",
  "arguments": {
    "category": "mastodon",
    "topic": "technology",
    "size": "medium"
  }
}

recommend-instances

Get personalized instance recommendations.

Input Schema:

{
  interests: string[]  // List of interests or topics
}

Example:

{
  "name": "recommend-instances",
  "arguments": {
    "interests": ["technology", "programming", "open source"]
  }
}

health-check

Check the health status of the MCP server.

Input Schema:

{}  // No parameters

Example:

{
  "name": "health-check",
  "arguments": {}
}

performance-metrics

Get performance metrics for the MCP server.

Input Schema:

{
  operation?: string  // Specific operation to get metrics for
}

Example:

{
  "name": "performance-metrics",
  "arguments": {
    "operation": "discover-actor"
  }
}

MCP Prompts

Prompts provide templates for guided workflows. See MCP Prompts for detailed documentation.

explore-fediverse

Get guidance on exploring the fediverse.

Arguments Schema:

{
  interests: string      // Your interests or topics
  instanceType?: string  // "mastodon" | "pleroma" | "misskey" | etc.
}

compare-instances

Get help comparing different instances.

Arguments Schema:

{
  instances: string   // Comma-separated list of domains
  criteria?: string   // Specific criteria for comparison
}

discover-content

Get recommendations for discovering content.

Arguments Schema:

{
  topics: string        // Comma-separated topics
  contentType?: string  // "people" | "hashtags" | "instances" | "all"
}

Response Formats

Tool Response

{
  content: [
    {
      type: "text",
      text: string  // Result description and data
    }
  ]
}

Resource Response

{
  contents: [
    {
      uri: string,
      mimeType: string,
      text: string  // JSON data
    }
  ]
}

Error Response

{
  error: {
    code: number,
    message: string
  }
}

Error Codes

  • 400 - Invalid request parameters
  • 404 - Resource not found
  • 429 - Rate limit exceeded
  • 500 - Internal server error
  • 503 - Service unavailable

Rate Limiting

Default rate limits:

  • Max requests: 100 per window
  • Window duration: 15 minutes (900000ms)
  • Per identifier: Tracked separately

Configure via environment variables:

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW=900000

Validation Schemas

Actor Identifier

Format: user@domain.tld

Example: Gargron@mastodon.social

Domain

Format: Valid domain name

Example: mastodon.social

Query

Format: Non-empty string

Max length: 500 characters

Next Steps

Made with ❤️ by Cameron Rye

Clone this wiki locally