MCP Integration Overview - Automagik Suite Documentation

Introduction

Forge’s Model Context Protocol (MCP) integration lets you control your entire task board from inside your AI coding agent. Never leave your editor - your AI manages Forge for you via natural language.

Quick value: Ask Claude “create a task to add dark mode” and it’s done. No UI clicking, no context switching, just flow.

What is MCP?

Model Context Protocol (MCP) is an open standard that allows AI agents to interact with external tools and services in a structured way. Think of it as “API for AI agents” - instead of you making HTTP requests, your AI agent does it automatically based on your conversation.

The Magic

❌ Without MCP:
You → Switch to Forge UI → Create task → Copy details → Switch back → Code

✅ With MCP:
You → "Create a task to add Redis caching"
AI → [Automatically creates task in Forge]
AI → "Task #47 created. Want me to start on it?"
You → Continue coding

Why Use MCP with Forge?

Stay in Flow

Never leave your editor. AI handles all Forge interactions while you focus on coding.

Natural Language

Use conversational commands. No need to remember CLI syntax or navigate UIs.

Faster Planning

“Plan an auth system” creates multiple tasks instantly. Seconds vs minutes.

Context Aware

AI sees your Forge tasks and suggests next steps based on your workflow.

Getting Started

Step 1: Get Your Project ID

Start Forge

npx automagik-forge

Opens browser at http://localhost:3000

Navigate to Project

Create or select a project and go to its task board.

Copy Project ID

Find it in the browser URL:

http://localhost:3000/projects/a1b2c3d4-e5f6-7890-abcd-ef1234567890/tasks
                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                              Copy this UUID

Or go to Project Settings and copy from there.

###Step 2: Choose Your Mode Forge offers two MCP modes:

Basic Mode (Recommended)
Advanced Mode

7 core tools for task management

npx automagik-forge --mcp

Best for: Most users. Clean, focused, fast.Tools:

list_projects - View all projects
list_tasks - Get tasks with filters
create_task - Add new tasks
get_task - View task details
update_task - Modify tasks
delete_task - Remove tasks

Start here! Upgrade to advanced only if you need it.

56 tools including worktrees, processes, filesystem

npx automagik-forge --mcp-advanced

Best for: Power users needing full control.Additional capabilities:

Git worktree management
Process control
File operations
Attempt management
Template system
Omni integration

Can overwhelm AI agents with too many options. Use basic mode first!

Step 3: Configure Your AI Agent

Choose your setup guide:

Claude Code

Setup for Claude Desktop and Claude Code

Cursor

Setup for Cursor IDE

VSCode + Cline

Setup for VSCode with Cline extension

Custom Client

Generic setup for any MCP client

Example Use Cases

Planning & Task Creation

You: "Help me plan a complete authentication system with OAuth, JWT,
     and role-based access control"

AI: [Uses MCP tools to analyze and create tasks]

AI: "I've created 8 tasks for your auth system:
     #42 - OAuth provider integration (Google, GitHub)
     #43 - JWT token generation and validation
     #44 - Refresh token mechanism
     #45 - Role-based permission middleware
     #46 - User session management
     #47 - Password reset flow
     #48 - Email verification
     #49 - Security audit and rate limiting

     Want me to prioritize them or start on any?"

Bug Tracking

You: "Add bug: API returns 500 on malformed JSON input in /api/users endpoint.
     Priority high, affects production"

AI: [Uses create_task via MCP]

AI: "Bug #50 logged:
     Title: Fix API crash on malformed JSON
     Priority: High
     Type: Bug
     Description: Production issue in /api/users endpoint

     Should I create an attempt to fix this now?"

Status Updates

You: "Show me all high-priority tasks that are blocked or pending"

AI: [Uses list_tasks with filters via MCP]

AI: "You have 3 high-priority tasks:

     Blocked:
     #45 - Waiting on OAuth library decision

     Pending:
     #47 - Ready to start password reset flow
     #48 - Email verification implementation ready

     Want me to start working on #47 or #48?"

Batch Operations

You: "Mark all database migration tasks as complete and move
     API tasks to in-progress"

AI: [Uses list_tasks + update_task via MCP]

AI: "Done:
     ✅ Marked 4 migration tasks complete
     🔄 Moved 3 API tasks to in-progress

     Current status:
     - 12 completed tasks
     - 3 in progress (API endpoints)
     - 5 pending

     Next priority is #52 - API documentation"

MCP Workflow Patterns

The Planning Flow

The Execution Flow

The Review Flow

Basic vs Advanced Comparison

Feature	Basic Mode	Advanced Mode
Tools	7 core tools	56 total tools
Task Management	✅ Full	✅ Full
Worktree Control	❌ Automatic only	✅ Manual control
Process Management	❌ No	✅ Yes
File Operations	❌ No	✅ Yes
Template System	❌ No	✅ Yes
Omni Integration	❌ No	✅ Yes
AI Response Speed	⚡ Fast	🐢 Slower (more options)
AI Response Quality	📝 Focused	🔀 Can be verbose
Best For	👥 Most users	🔧 Power users

90% of users should use Basic Mode. It’s faster, clearer, and does everything most people need.

Security & Privacy

Local-First

Forge MCP server runs 100% locally. No data leaves your machine. All operations happen on localhost.

Project Isolation

Each AI agent connects to a specific project ID:

{
  "env": {
    "PROJECT_ID": "proj_abc123"  // Agent can ONLY access this project
  }
}

Benefits:

No accidental cross-project operations
Multiple agents, multiple projects
Secure team collaboration

Troubleshooting

MCP server not connecting

Check:

Forge is installed: npm list -g @automagik/forge
Correct command in config: "command": "npx"
Correct args: "args": ["automagik-forge", "--mcp"]
Restart your AI agent after config changes

Solution: Reinstall Forge if needed:

npm install -g @automagik/forge

Project ID not found

Error: Project 'proj_xyz' not foundSolution:

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

AI gives confusing responses

Symptom: AI lists too many tools or seems uncertainSolution: You’re in advanced mode with 56 tools. Switch to basic:

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

Changes not appearing in UI

Solution: Refresh your browser. MCP changes happen in the database; UI needs refresh to show them.

Next Steps

Choose Your Agent

Pick which AI coding agent you use:

Configure MCP

Follow the setup guide for your chosen agent. Takes 2-3 minutes.

Test It Out

Try a simple command:

"Create a task to add a README file"

Your AI should create the task via MCP!

Explore Workflows

Learn advanced patterns:

Learn More

MCP Architecture

Deep dive into how MCP works in Forge

MCP Tools Reference

Complete list of all available tools

Workflows

See MCP in action with real examples

Troubleshooting

Fix common MCP issues

​Introduction

​What is MCP?

​The Magic

​Why Use MCP with Forge?

Stay in Flow

Natural Language

Faster Planning

Context Aware

​Getting Started

​Step 1: Get Your Project ID

​Step 3: Configure Your AI Agent

Claude Code

Cursor

VSCode + Cline

Custom Client

​Example Use Cases

​Planning & Task Creation

​Bug Tracking

​Status Updates

​Batch Operations

​MCP Workflow Patterns

​The Planning Flow

​The Execution Flow

​The Review Flow

​Basic vs Advanced Comparison

​Security & Privacy

​Local-First

​Project Isolation

​Troubleshooting

​Next Steps

​Learn More

MCP Architecture

MCP Tools Reference

Workflows

Troubleshooting

Introduction

What is MCP?

The Magic

Why Use MCP with Forge?

Getting Started

Step 1: Get Your Project ID

Step 3: Configure Your AI Agent

Example Use Cases

Planning & Task Creation

Bug Tracking

Status Updates

Batch Operations

MCP Workflow Patterns

The Planning Flow

The Execution Flow

The Review Flow

Basic vs Advanced Comparison

Security & Privacy

Local-First

Project Isolation

Troubleshooting

Next Steps

Learn More