Configuration Options

Customize the ActivityPub MCP Server behavior with environment variables, logging settings, and performance tuning options.

🔧 Environment Variables

Configure the server using environment variables in your MCP client configuration:

Variable	Default	Description	Example
`LOG_LEVEL`	`info`	Logging verbosity level	`debug`, `info`, `warning`, `error`, `fatal`
`USER_AGENT`	`ActivityPub-MCP-Server/1.0`	Custom User-Agent for HTTP requests	`MyApp-ActivityPub/2.0`
`REQUEST_TIMEOUT`	`30000`	HTTP request timeout in milliseconds	`45000` (45 seconds)
`CACHE_TTL`	`300`	Cache time-to-live in seconds	`600` (10 minutes)
`RATE_LIMIT_ENABLED`	`true`	Enable/disable rate limiting	`false` to disable
`RATE_LIMIT_MAX`	`100`	Maximum requests per window	`200`
`RATE_LIMIT_WINDOW`	`900000`	Rate limit window in milliseconds	`1800000` (30 minutes)

📝 Configuration Examples

Development Configuration

Optimized for development with verbose logging and relaxed limits:

{
  "mcpServers": {
    "activitypub": {
      "command": "npx",
      "args": ["-y", "activitypub-mcp"],
      "env": {
        "LOG_LEVEL": "debug",
        "REQUEST_TIMEOUT": "60000",
        "CACHE_TTL": "60",
        "RATE_LIMIT_ENABLED": "false"
      }
    }
  }
}

Production Configuration

Optimized for production with conservative settings:

{
  "mcpServers": {
    "activitypub": {
      "command": "npx",
      "args": ["-y", "activitypub-mcp"],
      "env": {
        "LOG_LEVEL": "warning",
        "REQUEST_TIMEOUT": "30000",
        "CACHE_TTL": "900",
        "RATE_LIMIT_ENABLED": "true",
        "RATE_LIMIT_MAX": "50",
        "USER_AGENT": "MyApp-ActivityPub/1.0"
      }
    }
  }
}

High-Performance Configuration

Optimized for high-throughput scenarios:

{
  "mcpServers": {
    "activitypub": {
      "command": "npx",
      "args": ["-y", "activitypub-mcp"],
      "env": {
        "LOG_LEVEL": "error",
        "REQUEST_TIMEOUT": "15000",
        "CACHE_TTL": "1800",
        "RATE_LIMIT_ENABLED": "true",
        "RATE_LIMIT_MAX": "200",
        "RATE_LIMIT_WINDOW": "600000"
      }
    }
  }
}

🎛️ Logging Configuration

Log Levels

`debug`

Detailed debugging information, HTTP requests/responses, internal state changes

Most Verbose

`info`

General operational messages, tool executions, resource access

Default

`warning`

Warning conditions, rate limiting, recoverable errors

Recommended

`error`

Error conditions, failed requests, unrecoverable issues

Errors Only

`fatal`

Critical errors that cause server shutdown

Critical Only

Log Output Examples

Debug Level Output

[DEBUG] HTTP Request: GET https://mastodon.social/.well-known/webfinger
[INFO] Discovering actor: @mastodon@mastodon.social
[DEBUG] WebFinger response received: 200 OK
[DEBUG] ActivityPub actor fetched successfully

Warning Level Output

[WARNING] Rate limit approaching for domain: example.social
[ERROR] Failed to fetch timeline: Network timeout

⚡ Performance Tuning

🚀 Request Timeout

Adjust REQUEST_TIMEOUT based on your network conditions:

Fast networks: 15-20 seconds
Standard networks: 30 seconds (default)
Slow networks: 45-60 seconds

💾 Cache Configuration

Optimize CACHE_TTL for your use case:

Real-time data: 60-300 seconds
General use: 300-600 seconds (default)
Static data: 1800+ seconds

🛡️ Rate Limiting

Configure rate limits to be respectful to fediverse servers:

Conservative: 50 requests per 15 minutes
Standard: 100 requests per 15 minutes (default)
Aggressive: 200 requests per 10 minutes

🔍 Configuration Validation

Test Your Configuration

Use these commands to validate your configuration:

Check Server Status

Verify the server starts with your configuration:

# Using MCP Inspector
npx @modelcontextprotocol/inspector

# Connect to: npx activitypub-mcp

Test Health Check

Use the health-check tool to verify functionality:

# In Claude Desktop or MCP Inspector
health-check --includeMetrics true

Monitor Logs

Check logs for configuration issues:

# Enable debug logging temporarily
"LOG_LEVEL": "debug"

🚀 Next Steps

Claude Desktop Integration

Apply your configuration to Claude Desktop integration.

Basic Usage Guide

Start using the server with your custom configuration.

Troubleshooting

Resolve configuration and performance issues.