MCP Tools Reference

Complete reference for all Model Context Protocol tools provided by the ActivityPub MCP Server. These tools enable LLMs to interact with the fediverse.

Discovery Tools

Tools for discovering actors, instances, and content across the fediverse.

discover-actor

Discover and get detailed information about fediverse actors (users).

Parameters

Name Type Required Description
identifier string Yes Actor identifier in WebFinger format (@user@domain) or ActivityPub URL

Examples

# WebFinger format
discover-actor @mastodon@mastodon.social

# ActivityPub URL
discover-actor https://mastodon.social/users/mastodon

# Profile URL
discover-actor https://mastodon.social/@mastodon

Response

Returns an ActivityPub Actor object with:

  • Actor ID and type
  • Display name and username
  • Profile information (bio, avatar, etc.)
  • Public key for verification
  • Endpoints (inbox, outbox, followers, etc.)

discover-instances

Discover popular fediverse instances by category, topic, or size.

Parameters

Name Type Required Description
category enum No Type of fediverse software: "mastodon", "pleroma", "misskey", "peertube", "pixelfed", "lemmy", or "all"
topic string No Topic or interest to search for (e.g., "technology", "art", "gaming")
size enum No Instance size preference: "small", "medium", or "large"
region string No Geographic region or language
beginnerFriendly boolean No Show only beginner-friendly instances

Examples

# Find Mastodon instances
discover-instances --category mastodon

# Find technology-focused instances
discover-instances --topic technology

# Find small, beginner-friendly instances
discover-instances --size small --beginnerFriendly true

# Find instances in a specific region
discover-instances --region europe

recommend-instances

Get personalized fediverse instance recommendations based on interests.

Parameters

Name Type Required Description
interests array Yes List of your interests or topics (e.g., ["technology", "opensource", "privacy"])

Examples

# Get recommendations based on interests
recommend-instances --interests ["technology", "opensource"]

# Multiple interests
recommend-instances --interests ["art", "photography", "design"]

Response

Returns personalized instance recommendations with:

  • Instance domain and name
  • Match score based on interests
  • Instance description and focus
  • User statistics
  • Registration status

Information Tools

Tools for getting information about instances, timelines, and content.

get-instance-info

Get detailed information about a fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain name (e.g., "mastodon.social")

Examples

# Get info about Mastodon.social
get-instance-info mastodon.social

# Check a smaller instance
get-instance-info fosstodon.org

Response

Returns instance metadata including:

  • Instance name and description
  • Software version and type
  • User and post statistics
  • Instance rules and policies
  • Contact information
  • Supported features

fetch-timeline

Fetch recent posts from any actor's timeline in the fediverse.

Parameters

Name Type Required Description
identifier string Yes Actor identifier (e.g., user@example.social)
limit number No Number of posts to fetch (default: 20, max: 50)

Examples

# Get recent posts from an actor
fetch-timeline user@mastodon.social

# Limit to 10 posts
fetch-timeline admin@fosstodon.org --limit 10

Response

Returns timeline data including:

  • Array of recent posts/activities
  • Post content and metadata
  • Author information
  • Engagement metrics (likes, boosts, replies)
  • Media attachments

search-instance

Search for content on a specific fediverse instance.

Parameters

Name Type Required Description
domain string Yes Instance domain (e.g., example.social)
query string Yes Search query
type enum No Type of content to search for: "accounts", "statuses", or "hashtags" (default: "accounts")

Examples

# Search for accounts
search-instance mastodon.social "opensource"

# Search for posts/statuses
search-instance fosstodon.org "linux" --type statuses

# Search for hashtags
search-instance pixelfed.social "photography" --type hashtags

Response

Returns search results based on type:

  • accounts: User profiles matching the query
  • statuses: Posts/toots containing the search terms
  • hashtags: Hashtags matching the query

Utility Tools

Additional tools for server management and debugging.

health-check

Check the health status of the ActivityPub MCP server.

Parameters

Name Type Required Description
includeMetrics boolean No Include detailed performance metrics in the response

Examples

# Basic health check
health-check

# Include detailed metrics
health-check --includeMetrics true

Response

Returns server status including:

  • Server uptime
  • Memory usage
  • Health status (healthy/degraded/unhealthy)
  • Optional: Detailed performance metrics

performance-metrics

Get detailed performance metrics for the ActivityPub MCP server.

Parameters

Name Type Required Description
operation string No Specific operation to get metrics for (e.g., 'discover-actor')

Examples

# Get all performance metrics
performance-metrics

# Get metrics for a specific operation
performance-metrics --operation discover-actor

Response

Returns performance data including:

  • Request counts by operation
  • Average response times
  • Success/failure rates
  • Cache hit rates
  • Resource utilization

Error Handling

All tools follow consistent error handling patterns:

Validation Errors

Returned when parameters are invalid or missing:

{`{
  "error": "Invalid parameter",
  "message": "Actor identifier must be in @user@domain format or valid URL",
  "code": "INVALID_PARAMETER"
}`}

Network Errors

Returned when external services are unreachable:

{`{
  "error": "Network error",
  "message": "Failed to connect to instance: connection timeout",
  "code": "NETWORK_ERROR"
}`}

Not Found Errors

Returned when requested resources don't exist:

{`{
  "error": "Not found",
  "message": "Actor not found or not accessible",
  "code": "NOT_FOUND"
}`}

Related Documentation

MCP Resources

Learn about the resources exposed by the server

Basic Usage Guide

See these tools in action with practical examples

Troubleshooting

Solutions for common tool-related issues