Claude Code Setup - Automagik Suite Documentation

Claude Code MCP Setup

Configure Forge as an MCP server for Claude Code in 3 minutes.

Works with both Claude Desktop and Claude Code (CLI). Same configuration for both.

Prerequisites

Install Forge

npm install -g @automagik/forge

Get Your Project ID

# Start Forge
npx automagik-forge

Open browser, navigate to your project, and copy the UUID from the URL:

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

Configuration

Option 1: Basic Mode (Recommended)

7 core tools for task management. Best for most users.

Open Claude Code Settings

macOS: Cmd + , or Claude Code → Settings
Windows/Linux: Ctrl + ,
Navigate to MCP Servers section

Add Forge Configuration

Add this to your MCP servers configuration:

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

Replace your-project-uuid-here with your actual Project ID.

Restart Claude Code

Fully quit and restart Claude Code for changes to take effect.

Test It

In Claude Code, try:

"Create a task to add a README file"

Claude should use the MCP tool to create the task in Forge!

Option 2: Advanced Mode

56 tools including worktrees, processes, filesystem. For power users.

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

Advanced mode can overwhelm Claude with too many tools. Start with basic mode first!

Available Tools

Basic Mode (7 tools)

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

Advanced Mode (+49 additional tools)

Includes all basic tools PLUS:

Project management (8 tools)
Task attempts (12 tools)
Process management (9 tools)
Git worktrees (7 tools)
File operations (6 tools)
Templates & drafts (5 tools)
Omni integration (8 tools)

Usage Examples

Task Creation

You: "Create a task to implement dark mode with LocalStorage persistence"

Claude: [Uses create_task MCP tool]

Claude: "I've created task #47: 'Implement dark mode toggle'
         - Priority: medium
         - Type: feature
         - Status: pending

         Would you like me to start working on it?"

Planning

You: "Help me plan a complete authentication system with OAuth, JWT, and RBAC"

Claude: [Uses create_task multiple times via MCP]

Claude: "I've created 8 tasks for your auth system:
         #42 - OAuth provider integration
         #43 - JWT token generation
         #44 - Refresh token mechanism
         #45 - Role-based permissions
         #46 - User session management
         #47 - Password reset flow
         #48 - Email verification
         #49 - Security audit

         Should I prioritize these or start on any?"

Status Checks

You: "Show me all high-priority bugs"

Claude: [Uses list_tasks with filters via MCP]

Claude: "You have 3 high-priority bugs:
         #35 - API crash on malformed JSON (pending)
         #38 - Memory leak in WebSocket (in progress)
         #41 - Auth token expiry issue (review)

         Want me to work on #35 first?"

Troubleshooting

MCP server not found

Error: Could not connect to MCP server 'automagik-forge'Solutions:

Verify Forge is installed:
npm list -g @automagik/forge
Check configuration syntax (valid JSON, no trailing commas)
Ensure "command": "npx" (not "node" or full path)
Restart Claude Code completely (quit and reopen)

Project not found error

Error: Project 'proj_xyz' does not existSolutions:

Verify project exists in Forge UI
Copy correct UUID from browser URL
Update PROJECT_ID in config
Restart Claude Code

Tools not appearing

Symptom: Claude doesn’t seem to have Forge toolsSolutions:

Ask Claude directly: “What MCP tools do you have access to?”
Check if automagik-forge appears in the list
If not, verify config and restart Claude Code

Too verbose responses

Symptom: Claude lists many tool options or seems confusedSolution: You’re in advanced mode (56 tools). Switch to basic:

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

Remove -advanced and restart.

Configuration File Location

Claude Code MCP configuration is stored in:

macOS
Windows
Linux

~/Library/Application Support/Claude/config.json

Or edit via Claude Code Settings UI.

%APPDATA%\Claude\config.json

Or edit via Claude Code Settings UI.

~/.config/Claude/config.json

Or edit via Claude Code Settings UI.

Best Practices

Use natural language: Don’t try to call tools directly. Just describe what you want, and Claude will use the right MCP tool.✅ Good: “Create a task to add Redis caching” ❌ Bad: “use create_task with title Redis”

Start with basic mode: Only upgrade to advanced if you need specific features like manual worktree control or filesystem operations.

One project per config: If you work on multiple projects, create separate MCP server entries with different PROJECT_IDs:

{
  "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 more about MCP integration

MCP Architecture

Understand how MCP works

MCP Tools Reference

Complete list of all MCP tools

Workflows

See MCP in action

​Claude Code MCP Setup

​Prerequisites

​Configuration

​Option 1: Basic Mode (Recommended)

​Option 2: Advanced Mode

​Available Tools

​Basic Mode (7 tools)

​Advanced Mode (+49 additional tools)

​Usage Examples

​Task Creation

​Planning

​Status Checks

​Troubleshooting

​Configuration File Location

​Best Practices

​Next Steps

MCP Overview

MCP Architecture

MCP Tools Reference

Workflows

Claude Code MCP Setup

Prerequisites

Configuration

Option 1: Basic Mode (Recommended)

Option 2: Advanced Mode

Available Tools

Basic Mode (7 tools)

Advanced Mode (+49 additional tools)

Usage Examples

Task Creation

Planning

Status Checks

Troubleshooting

Configuration File Location

Best Practices

Next Steps