MCP Architecture

Introduction

Forge implements the Model Context Protocol (MCP) as a built-in server, enabling any MCP-compatible AI agent to programmatically manage your tasks. Think of it as remote control for your Forge kanban - control everything without leaving your coding environment.

MCP in one sentence: A standardized protocol that lets AI agents interact with external tools and services in a structured, secure way.

What is Model Context Protocol?

The Concept

MCP is an open standard that allows AI agents to:

Discover available tools and capabilities
Invoke operations with structured parameters
Receive structured responses
Maintain context across multiple operations

Why MCP Matters

Before MCP
With MCP

The Old Way: Manual context switching

Code in your editor
Switch to Forge UI
Create task manually
Copy task details
Switch back to editor
Continue coding
Switch to Forge to check status
Repeat...

Result: Constant interruptions, lost context, broken flow

Forge’s MCP Implementation

Architecture Overview

Forge runs as both a web application AND an MCP server simultaneously:

Communication Flow

Agent Connects

When you start your AI agent (Claude Code, Cursor, etc.), it connects to Forge’s MCP server:

# Forge starts MCP server automatically
$ npx automagik-forge --mcp

# AI agent connects via stdio
AI Agent → MCP Server: CONNECT

Tool Discovery

The AI agent asks what tools are available:

AI Agent → Forge: "What tools do you have?"

Forge → AI Agent: {
  "tools": [
    {
      "name": "list_tasks",
      "description": "Get tasks with filters",
      "parameters": { "projectId": "string", "status": "string" }
    },
    {
      "name": "create_task",
      "description": "Create a new task",
      "parameters": { "title": "string", "description": "string" }
    },
    // ... more tools
  ]
}

Tool Invocation

You ask the AI to do something, it calls the appropriate tool:

You: "Create a task to add dark mode"

AI Agent → Forge MCP: call create_task({
  "projectId": "proj_abc123",
  "title": "Add dark mode toggle",
  "description": "Implement dark mode with LocalStorage persistence"
})

Forge → AI Agent: {
  "success": true,
  "taskId": "task_xyz789",
  "status": "pending"
}

Response Handling

The AI processes the response and tells you:

AI: "Task #47 created successfully. It's in pending status.
     Would you like me to start working on it?"

Two Modes: Basic vs Advanced

Forge offers two MCP modes with different tool sets:

Basic Mode (7 Tools)

Use when: You only need task management

# Start in basic mode
npx automagik-forge --mcp

Available Tools:

Tool	Purpose	Example
`list_projects`	Get all projects	”Show my projects”
`list_tasks`	Get tasks with filters	”Show pending tasks”
`create_task`	Create new task	”Add task: Fix bug in auth”
`get_task`	Get task details	”Show task #42”
`update_task`	Modify task	”Mark task #42 complete”
`delete_task`	Remove task	”Delete task #38”

Best for: Most users. Lighter weight, faster startup, clearer AI responses.

Advanced Mode (56 Tools)

Use when: You need full Forge control including worktrees, processes, filesystem

# Start in advanced mode
npx automagik-forge --mcp-advanced

Available Tools (Basic 7 + Additional 49):

Project Management (8 tools)

create_project
update_project
delete_project
get_project_stats
list_project_tasks
sync_project_repo
configure_project_llms
export_project

Task Attempts (12 tools)

create_attempt
list_attempts
get_attempt
start_attempt
stop_attempt
retry_attempt
compare_attempts
merge_attempt
discard_attempt
get_attempt_diff
get_attempt_logs
set_attempt_status

Process Management (9 tools)

list_processes
get_process
start_process
stop_process
restart_process
get_process_logs
kill_process
process_health_check
cleanup_processes

Git Worktrees (7 tools)

list_worktrees
create_worktree
remove_worktree
cleanup_worktrees
worktree_status
worktree_diff
lock_worktree

Drafts & Templates (5 tools)

list_drafts
create_draft
apply_draft
list_templates
create_from_template

Filesystem Operations (6 tools)

read_file
write_file
list_files
file_diff
search_files
get_file_info

Omni Integration (8 tools)

send_notification
list_integrations
configure_webhook
send_message (to WhatsApp, Discord, etc.)
get_message_status
And more…

Advanced mode can overwhelm AI agents with too many tools. They may struggle to choose the right one or give verbose responses. Use basic mode unless you specifically need advanced features.

Security & Authentication

Project ID Requirement

All MCP operations require a Project ID for security and isolation:

{
  "mcpServers": {
    "automagik-forge": {
      "command": "npx",
      "args": ["automagik-forge", "--mcp"],
      "env": {
        "PROJECT_ID": "proj_abc123"  // ← Required!
      }
    }
  }
}

Why?

Isolation: Agent can only access specified project
Multi-project: Run multiple Forge instances with different agents
Security: Prevents accidental cross-project operations

Getting Your Project ID

Start Forge UI

npx automagik-forge

Opens browser at http://localhost:3000

Create or Select Project

Create new project or select existing one
Navigate to the project’s task board

Get ID from URL

http://localhost:3000/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                              Your Project ID

Or find it in Project Settings panel.

Add to MCP Config

Copy the UUID and add to your AI agent’s MCP configuration.

Data Privacy

Forge MCP server runs locally on your machine. No data is sent to external servers. All operations happen on localhost.

Typical Workflows

Planning Workflow

Bug Discovery Workflow

Status Update Workflow

You: "Mark auth tasks as complete"

AI → MCP: list_tasks(filter: "auth")
MCP → AI: [Returns 3 auth tasks]

AI → MCP: update_task(task_45, status: "completed")
AI → MCP: update_task(task_46, status: "completed")
AI → MCP: update_task(task_47, status: "completed")

AI: "Marked 3 authentication tasks as completed ✅"

Best Practices

DO ✅

Use Basic Mode First

Start with --mcp (7 tools). Only upgrade to --mcp-advanced if you need specific advanced features.

# Start here
npx automagik-forge --mcp

# Only if needed
npx automagik-forge --mcp-advanced

One Project ID Per Agent

Configure each AI agent with a specific project ID:

// Claude Code → Project A
{
  "env": { "PROJECT_ID": "proj_frontend123" }
}

// Cursor → Project B
{
  "env": { "PROJECT_ID": "proj_backend456" }
}

Use Natural Language

MCP tools work best with conversational requests:

✅ "Create a task to add Redis caching with TTL config"
✅ "Show me all high-priority bugs"
✅ "Mark task #42 as complete and create a follow-up for documentation"

❌ create_task(title="Redis", desc="cache")
❌ list_tasks()

Let the AI translate your intent to MCP calls.

DON’T ❌

Don’t mix MCP modes for the same project. Pick basic OR advanced, not both.

Don’t share Project IDs across users. Each developer should have their own project or use different IDs.

Don’t forget to restart your AI agent after changing MCP configuration.

Troubleshooting

MCP Server Not Found

Error: MCP server 'automagik-forge' not found

Solution:

Make sure Forge is installed: npm install -g automagik-forge
Verify command in config is correct: "command": "npx"
Check args: "args": ["automagik-forge", "--mcp"]
Restart your AI agent

Project ID Invalid

Error: Project 'proj_abc123' not found

Solution:

Open Forge UI: npx automagik-forge
Verify project exists
Copy correct UUID from browser URL
Update MCP config with correct ID
Restart AI agent

Too Many Tools (Advanced Mode)

AI: "I see many tools available. Which one should I use?"

Solution: Switch to basic mode

{
  "args": ["automagik-forge", "--mcp"]  // Remove -advanced
}

Next Steps

MCP Setup Guides

Configure MCP for your AI agent

MCP Tools Reference

Complete list of all available tools

Claude Code Setup

MCP configuration for Claude Code

Cursor Setup

MCP configuration for Cursor

Getting Started

Learn

Configuration

Reference

Troubleshooting

Introduction

What is Model Context Protocol?

The Concept

Why MCP Matters

Forge’s MCP Implementation

Architecture Overview

Communication Flow

Two Modes: Basic vs Advanced

Basic Mode (7 Tools)

Advanced Mode (56 Tools)

Security & Authentication

Project ID Requirement

Getting Your Project ID

Data Privacy

Typical Workflows

Planning Workflow

Bug Discovery Workflow

Status Update Workflow

Best Practices

DO ✅

DON’T ❌

Troubleshooting

MCP Server Not Found

Project ID Invalid

Too Many Tools (Advanced Mode)

Next Steps

MCP Setup Guides

MCP Tools Reference

Claude Code Setup

Cursor Setup

Getting Started

Learn

Configuration

Reference

Troubleshooting

​Introduction

​What is Model Context Protocol?

​The Concept

​Why MCP Matters

​Forge’s MCP Implementation

​Architecture Overview

​Communication Flow

​Two Modes: Basic vs Advanced

​Basic Mode (7 Tools)

​Advanced Mode (56 Tools)

​Security & Authentication

​Project ID Requirement

​Getting Your Project ID

​Data Privacy

​Typical Workflows

​Planning Workflow

​Bug Discovery Workflow

​Status Update Workflow

​Best Practices

​DO ✅

​DON’T ❌

​Troubleshooting

​MCP Server Not Found

​Project ID Invalid

​Too Many Tools (Advanced Mode)

​Next Steps

MCP Setup Guides

MCP Tools Reference

Claude Code Setup

Cursor Setup

Introduction

What is Model Context Protocol?

The Concept

Why MCP Matters

Forge’s MCP Implementation

Architecture Overview

Communication Flow

Two Modes: Basic vs Advanced

Basic Mode (7 Tools)

Advanced Mode (56 Tools)

Security & Authentication

Project ID Requirement

Getting Your Project ID

Data Privacy

Typical Workflows

Planning Workflow

Bug Discovery Workflow

Status Update Workflow

Best Practices

DO ✅

DON’T ❌

Troubleshooting

MCP Server Not Found

Project ID Invalid

Too Many Tools (Advanced Mode)

Next Steps