@forked-online/mcp

A Model Context Protocol server for forked.online. Lets any MCP-capable agent (Claude Code, Claude Desktop, claude.ai, IDE plugins) read your work items / projects and write activities, todos, work items, and thread messages back to the platform.

The loop it enables

1. You create a work item with the issue/spec in its body.
2. You paste the URL into your agent: "address this https://forked.online/work_items/47".
3. The agent calls get_work_item to read the spec, plans with you, breaks the plan into todos via create_todo, works through them calling complete_todo, then closes with log_activity carrying a markdown narrative of what it did.

Install

Don't install directly — drop a config snippet into your agent. npx pulls and caches the package on first run, so no clone, no build, works the same on your laptop and on any remote box you run an agent on.

Grab your workspace API key from forked.online/platform_settings?tab=api_keys.

Claude Code

Paste into ~/.claude.json:

{
  "mcpServers": {
    "forked-online": {
      "command": "npx",
      "args": ["-y", "@forked-online/mcp@latest"],
      "env": {
        "FORKED_API_KEY": "fkd_...",
        "FORKED_BASE_URL": "https://forked.online"
      }
    }
  }
}

Restart Claude Code. Verify with /mcp — forked-online should appear with its tools.

Hermes Agent

Paste into ~/.hermes/config.yaml:

mcp_servers:
  forked-online:
    command: "npx"
    args: ["-y", "@forked-online/mcp@latest"]
    env:
      FORKED_API_KEY: "fkd_..."
      FORKED_BASE_URL: "https://forked.online"

Restart hermes gateway. Confirm the server attached in the Hermes logs.

OpenCode

Paste into ~/.config/opencode/opencode.json (global) or an opencode.json at the root of a specific project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "forked-online": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "@forked-online/mcp@latest"],
      "environment": {
        "FORKED_API_KEY": "fkd_...",
        "FORKED_BASE_URL": "https://forked.online"
      }
    }
  }
}

Restart opencode. Verify with /mcp list.

Anything else MCP-capable

Stdio transport, command npx -y @forked-online/mcp@latest, env FORKED_API_KEY and FORKED_BASE_URL.

Visual verification (Playwright MCP)

When an agent's change touches the visual layer (views, frontend, styling), the orchestrator directive tells it to open the running app in a browser via the Playwright MCP, screenshot each changed screen, and record them on the work item with log_playwright_verification — so you scroll the screenshots during PR review. The screenshots upload as a playwright_verification activity (image attachments) on the WI timeline.

For this the agent needs the Playwright MCP available alongside forked-online:

• In a pod: nothing to do — the platform pins @playwright/mcp as a headless builtin on every dispatched agent (a pod has no display).

• Local Claude Code (so you watch it live): add @playwright/mcp yourself, headed — the default, so don't pass --headless — and the browser window pops up on your machine, showing exactly what the agent does:

  claude mcp add playwright -- npx -y @playwright/mcp@latest

  Or in ~/.claude.json, next to forked-online:

  "playwright": {
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest"]
  }

Tools

Read

• get_work_item { ref } — fetch one work item (URL / WI-NNNN / number). Returns body_markdown.
• list_work_items { status?, kind?, project_slug? } — browse.
• get_project { slug } — project + phases + tech.
• list_projects { kind? } — active projects.
• list_todos { work_item_ref?, project_slug?, completed? } — browse todos.

Write

• create_work_item { title, kind, priority?, status?, project_slug?, phase_id?, summary?, body_markdown?, tech_tags? } — file a new work item from the agent. Drop the agreed plan into body_markdown.
• update_work_item { work_item_ref, priority?, summary?, body_markdown? } — refine the plan body, summary, or priority after creation. Status flips use set_work_item_status.
• create_todo { title, priority?, work_item_ref?, project_slug?, due_at?, notes?, tech_tags? } — new todo. Inherits project + phase from work_item_ref.
• complete_todo { id } — mark done. Idempotent.
• log_activity { kind, title, body_markdown?, work_item_ref?, project_slug?, tech_tags?, duration_minutes? } — capture finished work. Always pass body_markdown — it becomes the activity page.
• log_playwright_verification { work_item_ref, status, screenshots, title?, body_markdown? } — record a browser/visual verification with screenshots. screenshots is an array of absolute file paths; the server reads them off disk and uploads them. The only way to create a playwright_verification activity. See Visual verification.
• post_thread_message { work_item_ref, body_markdown } — mid-work updates. Auto-creates the thread if eligible.
• set_work_item_status { work_item_ref, status } — open, in_progress, blocked, resolved, closed, archived.

URL parsing

Every *_ref arg accepts:

• A full URL: https://forked.online/work_items/42
• A reference: WI-0042
• A bare number: 42

So you can paste links verbatim.

Env vars

| Var | Required | Default | Notes | |-----|----------|---------|-------| | FORKED_API_KEY | yes | — | fkd_... workspace key. | | FORKED_BASE_URL | no | https://forked.online | Override for local dev. |

Auth model (v1)

Today the API uses a single workspace-scoped key (fkd_...). Every tool call is "on behalf of the workspace owner" — thread messages, for example, are authored as the owner. Per-agent revocable tokens are a v2 addition.

Local development

If you're hacking on the server itself, clone the monorepo and run it from source:

git clone https://github.com/mrvigneshvt/Forked.Online.git
cd Forked.Online/mcp
npm install
npm run dev       # tsc --watch
FORKED_API_KEY=fkd_... FORKED_BASE_URL=http://localhost:3017 node dist/index.js

Then point your agent config at the local dist/index.js instead of npx.

Speak MCP to it via stdin to verify:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | FORKED_API_KEY=$KEY node dist/index.js