Custom MCP Clients - Automagik Suite Documentation

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

Field	Value	Description
`command`	`"npx"`	Package runner command
`args`	`["automagik-forge", "--mcp"]`	Forge with MCP mode
`PROJECT_ID`	UUID	Your Forge project ID

Optional Fields

Field	Value	Description
`name`	`"automagik-forge"`	Server name identifier
`type`	`"stdio"`	Communication protocol
`description`	Custom text	Server description

Getting Your Project ID

Start Forge

npx automagik-forge

Navigate to Project

Open browser, create or select your project

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

Find your client's MCP config location

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

Verify Forge is accessible

Test Forge command directly:

npx automagik-forge --mcp

Should start the MCP server without errors.

Check Project ID validity

Ensure:

Project exists in Forge UI
UUID is exact (no extra spaces/quotes)
Format is correct: proj_xxxxx or full UUID

Enable debug logging

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

​Custom MCP Client Setup

​Generic Configuration Pattern

​Standard Configuration

​Advanced Mode

​Common MCP Clients

​Roo Code

​Gemini CLI

​Continue.dev

​Configuration Elements

​Required Fields

​Optional Fields

​Getting Your Project ID

​Testing Your Configuration

​Troubleshooting

​Configuration Formats

​JSON (Most Common)

​YAML

​TOML

​Advanced: Multiple Projects

​Next Steps