Skip to main content

​
Custom MCP Client Setup

Configure Forge as an MCP server for any MCP-compatible tool.

​
Generic Configuration Pattern

All MCP clients follow a similar pattern. Forge uses standard MCP protocol.

​
Standard Configuration

{
  "command": "npx",
  "args": ["automagik-forge", "--mcp"],
  "env": {
    "PROJECT_ID": "your-project-uuid-here"
  }
}

​
Advanced Mode

{
  "command": "npx",
  "args": ["automagik-forge", "--mcp-advanced"],
  "env": {
    "PROJECT_ID": "your-project-uuid-here"
  }
}

​
Common MCP Clients

​
Roo Code

servers:
  automagik-forge:
    command: npx
    args:
      - automagik-forge
      - --mcp
    environment:
      PROJECT_ID: your-project-uuid-here

​
Gemini CLI

{
  "mcp": {
    "servers": {
      "automagik-forge": {
        "type": "stdio",
        "command": "npx",
        "args": ["automagik-forge", "--mcp"],
        "env": {
          "PROJECT_ID": "your-project-uuid-here"
        }
      }
    }
  }
}

​
Continue.dev

{
  "mcpServers": {
    "automagik-forge": {
      "command": "npx",
      "args": ["automagik-forge", "--mcp"],
      "env": {
        "PROJECT_ID": "your-project-uuid-here"
      }
    }
  }
}

​
Configuration Elements

​
Required Fields

FieldValueDescription
command"npx"Package runner command
args["automagik-forge", "--mcp"]Forge with MCP mode
PROJECT_IDUUIDYour Forge project ID

​
Optional Fields

FieldValueDescription
name"automagik-forge"Server name identifier
type"stdio"Communication protocol
descriptionCustom textServer description

​
Getting Your Project ID

1

Start Forge

npx automagik-forge
2

Navigate to Project

Open browser, create or select your project
3

Copy UUID

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

​
Testing Your Configuration

After configuring, test with these commands: 
"What MCP servers do you have?"
Should show automagik-forge in the list. 
"Create a task to add a README file"
Should create task #X in Forge. 
"Show my pending tasks"
Should list tasks from Forge.

​
Troubleshooting

Check your client’s documentation for:
  • “MCP configuration”
  • “External tools”
  • “Model Context Protocol”
  • “Extensions” or “Plugins”
Common locations:
  • Settings UI → MCP Servers
  • Preferences → Tools → MCP
  • Config file: ~/.config/<client>/config.json
Test Forge command directly:
npx automagik-forge --mcp
Should start the MCP server without errors.
Ensure:
  1. Project exists in Forge UI
  2. UUID is exact (no extra spaces/quotes)
  3. Format is correct: proj_xxxxx or full UUID
Some clients support debug mode:
{
  "env": {
    "PROJECT_ID": "...",
    "DEBUG": "mcp:*"
  }
}
Check client logs for MCP connection errors.

​
Configuration Formats

Different clients use different formats:

​
JSON (Most Common)

{
  "mcpServers": {
    "automagik-forge": {
      "command": "npx",
      "args": ["automagik-forge", "--mcp"],
      "env": { "PROJECT_ID": "..." }
    }
  }
}

​
YAML

mcpServers:
  automagik-forge:
    command: npx
    args:
      - automagik-forge
      - --mcp
    env:
      PROJECT_ID: your-project-uuid

​
TOML

[mcpServers.automagik-forge]
command = "npx"
args = ["automagik-forge", "--mcp"]

[mcpServers.automagik-forge.env]
PROJECT_ID = "your-project-uuid"

​
Advanced: Multiple Projects

Configure multiple Forge projects: 
{
  "mcpServers": {
    "forge-frontend": {
      "command": "npx",
      "args": ["automagik-forge", "--mcp"],
      "env": { "PROJECT_ID": "proj_frontend123" }
    },
    "forge-backend": {
      "command": "npx",
      "args": ["automagik-forge", "--mcp"],
      "env": { "PROJECT_ID": "proj_backend456" }
    }
  }
}

​
Next Steps

MCP Overview

Learn about MCP integration

MCP Tools Reference

See all available MCP tools

Report Issues

Get help with your specific client