# Pitchfork MCP Server Documentation

The Pitchfork Public API includes a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that allows AI coding agents and LLM-powered tools to manage your bot farm programmatically.

## Overview

The MCP server exposes 8 AI-optimized tools that cover all management operations: accounts, proxies, scripts, triggers, agents, groups, client instances, and account tools. Each tool uses an `action` parameter to select the operation, keeping the tool count low while providing full coverage.

## Transports

The server supports two MCP transport protocols:

### Streamable HTTP (Recommended)
- **Endpoint:** `POST /mcp`
- Modern, efficient transport. Send JSON-RPC requests and receive responses over a single HTTP connection.
- Supports request/response and server-sent notifications.

### Server-Sent Events (SSE)
- **Endpoint:** `GET /mcp/sse`
- Legacy transport for clients that don't support Streamable HTTP.
- Opens a persistent SSE connection for server-to-client messages.

## Authentication

All MCP requests require a valid API key. Obtain one from **Account Settings > API Keys** in the web UI, or via the REST API at `/api/public/v1/api-keys`.

Pass your API key using one of these methods:

| Method | Header | Example |
|--------|--------|---------|
| X-API-Key header | `X-API-Key: pfk_...` | Recommended for MCP clients |
| Bearer token | `Authorization: Bearer pfk_...` | Standard OAuth-style |

API keys have permission levels:
- **Read-only:** Can list/get resources
- **Read-write:** Full access to all operations

### Rate Limiting

MCP endpoints are rate-limited to **1,000 requests per hour** per API key. Exceeding the limit returns HTTP 429 with a `Retry-After` header.

## One-click setup prompt

Paste the prompt below into any AI coding assistant (Claude, ChatGPT, Cursor, Windsurf, etc.) and it will produce the exact configuration block for your client:

```
You are helping me wire the Pitchfork MCP server into my AI client.

Authoritative docs:
- https://api.getpitchfork.com/docs/mcp
- https://api.getpitchfork.com/docs/mcp/agent-instructions

Endpoint:        https://api.getpitchfork.com/mcp   (Streamable HTTP, recommended)
Legacy SSE:      https://api.getpitchfork.com/mcp/sse
Auth header:     X-API-Key: <PASTE_KEY_HERE>
                 (or Authorization: Bearer <PASTE_KEY_HERE>)

Tasks:
1. Detect the MCP client I'm using (Claude Desktop, Cursor, Windsurf, Continue, custom).
2. Output the exact JSON / config block I need to add, with the endpoint and X-API-Key header.
3. Tell me where on disk that config lives for my OS.
4. List 3 example tool calls I can run to verify it works (start with `manage_accounts` action=`list`).

Rules:
- Only use the endpoints and tool names defined in the docs above. Do not invent fields.
- If I haven't pasted my API key yet, leave a clear `<PASTE_KEY_HERE>` placeholder.
```

The web dashboard at `/protected/mcp` has a button that copies this prompt to your clipboard. The browser only sees the API key prefix (e.g. `pfk_live_a1b2c3…`), so the copied prompt always uses the `<PASTE_KEY_HERE>` placeholder — paste your full secret key in yourself before sending it to the assistant.

## Client Configuration

### Claude Desktop / Cursor / Windsurf

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "pitchfork": {
      "url": "https://api.getpitchfork.com/mcp",
      "headers": {
        "X-API-Key": "pfk_your_api_key_here"
      }
    }
  }
}
```

### Custom Integration

Connect using any MCP-compatible client library. The server implements the standard MCP protocol with tool discovery via `tools/list`.

```python
# Python example using the MCP SDK
from mcp import Client

client = Client("https://api.getpitchfork.com/mcp")
client.headers["X-API-Key"] = "pfk_your_api_key_here"

# List available tools
tools = await client.list_tools()

# Call a tool
result = await client.call_tool("manage_accounts", {"action": "list"})
```

## Available Tools

### manage_accounts
Manage OSRS accounts. List supports `page` / `page_size` / `state` / `group_id` filters. Actions:

- **CRUD:** list, get, create, update, delete
- **Search & I/O:** search, import, export
- **Operations:** stop, auth_capture, metadata_update, bulk_rename
- **Proxy pairing:** proxy_pairing_preview, proxy_pairing_apply, proxy_assignments_get, proxy_assignments_delete, proxy_reassign

### manage_proxies
Manage proxies and proxy groups — list, get, create, update, delete, list_groups, create_group, update_group, delete_group.

### manage_scripts
Manage script activities — list, get, create, update, delete, start, stop, clone.

### manage_triggers
Manage metadata triggers — list, get, create, update, delete, toggle, history.

### manage_agents
Manage agent instances — list, get, create, update, delete, duplicate, get_settings, update_settings.

### manage_groups
Manage account groups — list, get, create, update, delete, assign_accounts.

### manage_client_instances
Manage templated client launch configurations — list, get, create, update, delete, launch. The `launch` action requires `id`, `agent_id`, and `account_id` and dispatches a real launch via the BMS internal API.

### manage_account_tools
Run automated account tools (paid plan required) — list, history, status, start. Supported tools: `ban_appealer`, `jagex_upgrader`, `account_creator`, `2fa_enabler`, `status_checker`. The `start` action returns a `task_id` which can be polled with `status`.

## Examples

### List all accounts
```json
{
  "tool": "manage_accounts",
  "arguments": {"action": "list"}
}
```

### Create an account
```json
{
  "tool": "manage_accounts",
  "arguments": {
    "action": "create",
    "login": "user@email.com",
    "password": "mypassword",
    "display_name": "GoldFarmer1",
    "group_id": 3
  }
}
```

### Bulk import accounts
```json
{
  "tool": "manage_accounts",
  "arguments": {
    "action": "import",
    "accounts": [
      {"login": "acc1@email.com", "password": "pass1"},
      {"login": "acc2@email.com", "password": "pass2", "group_id": 5}
    ]
  }
}
```

### Create a proxy
```json
{
  "tool": "manage_proxies",
  "arguments": {
    "action": "create",
    "ip": "192.168.1.100",
    "port": 1080,
    "proxy_type": "socks5",
    "username": "proxyuser",
    "password": "proxypass"
  }
}
```

### Start a script
```json
{
  "tool": "manage_scripts",
  "arguments": {"action": "start", "id": 42}
}
```

### Create and enable a trigger
```json
{
  "tool": "manage_triggers",
  "arguments": {
    "action": "create",
    "name": "Low HP Alert",
    "trigger_type": "metadata_threshold",
    "conditions": {"field": "hitpoints", "operator": "lt", "value": 10},
    "actions": {"type": "stop_account"}
  }
}
```

## Agent Instructions

For AI agents connecting to this MCP server, a detailed instructions file is available at:
- **URL:** `/docs/mcp/agent-instructions`
- **Format:** Markdown text optimized for LLM consumption

This file contains the complete tool reference with all parameters, required fields, and usage patterns.

## REST API

The full REST API documentation is available via Swagger UI at `/swagger/`. The MCP server provides the same capabilities as the REST API but packaged for AI agent consumption.

## Support

- **Discord:** [discord.gg/oldschoolrs](https://discord.gg/oldschoolrs)
- **API Issues:** Contact support via the web dashboard