MCP Setup

Stdio Mode (Claude Desktop)

For local development, configure Claude Desktop to use MiniAPM’s MCP server.

1. Generate Configuration

Run the following command to get your Claude Desktop configuration:

miniapm mcp-config

This outputs the JSON configuration to add to Claude Desktop.

2. Configure Claude Desktop

Open Claude Desktop settings and add the MiniAPM MCP server:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "miniapm": {
      "command": "/path/to/miniapm",
      "args": ["mcp"]
    }
  }
}

If using Docker:

{
  "mcpServers": {
    "miniapm": {
      "command": "docker",
      "args": [
        "exec", "-i", "miniapm-container",
        "/miniapm", "mcp"
      ]
    }
  }
}

3. Restart Claude Desktop

Restart Claude Desktop to load the new configuration. You should see “miniapm” listed as an available tool.

4. Test the Connection

Ask Claude: “Can you check the system status from MiniAPM?”

HTTP Mode (Remote Access)

For remote or shared access, use the HTTP MCP endpoint.

Endpoint

POST /mcp

Authentication

Include your API key in the Authorization header:

Authorization: Bearer proj_abc123...

Request Format

MCP uses JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_errors",
    "arguments": {
      "limit": 10
    }
  }
}

Example Request

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer proj_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "system_status",
      "arguments": {}
    }
  }'

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "System Status:\n- Total Errors (24h): 15\n- Error Rate: 0.5%\n- Avg Response Time: 120ms\n- Active Traces: 1,234"
      }
    ]
  }
}

Claude API Integration

You can also use MCP tools programmatically with the Claude API:

import anthropic

client = anthropic.Client()

# Define the MiniAPM MCP tools
tools = [
    {
        "name": "list_errors",
        "description": "List recent errors from MiniAPM",
        "input_schema": {
            "type": "object",
            "properties": {
                "limit": {"type": "integer", "default": 10},
                "status": {"type": "string", "enum": ["open", "resolved", "ignored"]}
            }
        }
    }
]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    tools=tools,
    messages=[
        {"role": "user", "content": "What errors happened today?"}
    ]
)

# Handle tool calls and forward to MiniAPM

Troubleshooting

Claude Desktop doesn’t show MiniAPM

1. Check the configuration file path is correct
2. Ensure the miniapm binary path is absolute
3. Check Claude Desktop logs for errors
4. Restart Claude Desktop completely

Connection Refused

1. Ensure MiniAPM is running
2. Check the port is correct (default: 3000)
3. Verify network access if using remote mode

Authentication Errors

1. Verify your API key is correct
2. Check the Authorization header format: Bearer <key>
3. Ensure the key has MCP access (all keys do by default)

Security Considerations

• Stdio mode runs locally and inherits your permissions
• HTTP mode requires API key authentication
• MCP provides read-only access to APM data
• No destructive operations are exposed via MCP