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/@mastodonResponse
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
Find fediverse instances by category, topic, or search criteria.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
query | string | No | Search term or category (e.g., "technology", "art", "gaming") |
limit | number | No | Maximum number of results to return (default: 20, max: 100) |
Examples
# Find technology-focused instances
discover-instances technology
# Find art communities
discover-instances art
# Get popular instances (no query)
discover-instances📊 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.orgResponse
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 an actor's public timeline.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
actor_url | string | Yes | ActivityPub URL of the actor |
limit | number | No | Number of posts to fetch (default: 20, max: 50) |
Examples
# Get recent posts from an actor
fetch-timeline https://mastodon.social/users/mastodon
# Limit to 10 posts
fetch-timeline https://fosstodon.org/users/admin 10🔧 Utility Tools
Additional tools for server management and debugging.
health-check
Check the health and status of the MCP server.
Parameters
No parameters required.
Examples
# Check server health
health-checkResponse
Returns server status including:
- Server uptime
- Memory usage
- Cache statistics
- Recent error counts
- Performance metrics
clear-cache
Clear the server's internal cache to force fresh data retrieval.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cache_type | string | No | Type of cache to clear: "actors", "instances", "timelines", or "all" |
Examples
# Clear all caches
clear-cache
# Clear only actor cache
clear-cache actors
# Clear instance information cache
clear-cache instances⚠️ 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"
}`}