Claude Code Setup

Connect Claude Code to Agiflow using MCP for seamless project management, scaffolding, and architecture validation. Choose from three connection methods based on your workflow.

Prerequisites

Claude Code installed

Download from claude.com/claude-code

Agiflow account and project

Create a free account at agiflow.io

Choose Your Connection Method

Method 1: Marketplace + HTTP MCP (Recommended)

The easiest setup with automatic updates via Claude Code's marketplace. Direct HTTP connection to Agiflow API.

✅ Easiest setup • ✅ Automatic updates • ✅ Simple configuration • ⚠️ Requires internet connection

Method 2: Powertool (stdio MCP)

Use @agiflowai/powertool as a local stdio MCP proxy. Works alongside platform-tools for enhanced capabilities.

✅ Works with platform-tools • ✅ Local proxy control • ℹ️ Requires npm package • ℹ️ Manual configuration

Method 3: Agent-CLI (Local Daemon)

Connect to a locally running agent-cli daemon for advanced session management, model routing, and task tracking.

✅ Full session management • ✅ Model routing • ✅ Task tracking • ℹ️ Requires agent-cli daemon running

Method 1: Marketplace + HTTP MCP

The easiest way to connect Claude Code with automatic updates and built-in configuration.

Step 1: Get Your API Key

From your Agiflow dashboard, navigate to your project and click the Actions menu, then select Project MCP.

Select HTTP MCP + Marketplace as the setup method, then click Generate API Key to create a new API key for your MCP connection.

Step 2: Install from Marketplace

Open Claude Code and access the MCP marketplace (Settings → MCP Servers → Browse Marketplace).

Search for "Agiflow Project MCP" and click Install.

Step 3: Configure Connection

After installation, you'll be prompted to configure the connection with your project URL and API key.

Project MCP URL format:

https://agiflow.io/api/v1/organizations/YOUR_ORG_ID/projects/YOUR_PROJECT_ID/mcp

💡 Tip: Copy the exact URL from the MCP setup dialog in your Agiflow dashboard to avoid errors.

Alternative: Manual Configuration

If you prefer manual setup, edit your Claude Code configuration file and add this JSON:

# Config file location

~/.config/claude/mcp_settings.json (macOS/Linux)

%APPDATA%\Claude\mcp_settings.json (Windows)

{
  "mcpServers": {
    "agiflow-project-mcp": {
      "type": "http",
      "url": "https://agiflow.io/api/v1/organizations/YOUR_ORG_ID/projects/YOUR_PROJECT_ID/mcp",
      "headers": {
        "X-API-KEY": "your-generated-api-key"
      }
    }
  }
}

Method 2: Powertool (stdio MCP)

Use @agiflowai/powertool as a local stdio MCP proxy that fetches configuration from Agiflow.

Step 1: Get Configuration from Dashboard

From your project's MCP setup dialog, select stdio MCP Proxy as the setup method, then click Generate API Key.

You'll see two sections: environment variables and MCP configuration JSON.

Step 2: Set Environment Variables

Copy the export commands and add them to your shell profile:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile

export AGIFLOW_MCP_PROXY_ENDPOINT="https://agiflow.io/api/v1/organizations/YOUR_ORG_ID/projects/YOUR_PROJECT_ID/mcp-configs"
export AGIFLOW_MCP_API_KEY="your-generated-api-key"

Step 3: Add to Claude Code Config

Edit your Claude Code MCP settings file and add the powertool configuration:

Configuration:

{
  "mcpServers": {
    "agiflow-project-mcp": {
      "command": "npx",
      "args": ["-y", "@agiflowai/powertool", "mcp-serve"],
      "env": {
        "AGIFLOW_MCP_PROXY_ENDPOINT": "${AGIFLOW_MCP_PROXY_ENDPOINT}",
        "AGIFLOW_MCP_API_KEY": "${AGIFLOW_MCP_API_KEY}"
      }
    }
  }
}

Step 4: Restart Claude Code

Completely restart Claude Code (quit and reopen) to load the environment variables and new MCP server configuration.

Method 3: Agent-CLI (Local Daemon)

Connect to a locally running agent-cli daemon for advanced session management and model routing capabilities.

Step 1: Install Agent-CLI

Install the @agiflowai/agent-cli package globally:

# Install globally

npm install -g @agiflowai/agent-cli

Step 2: Connect and Authenticate

Authenticate with Agiflow using the device code flow:

# Connect and authenticate

agent-cli connect

💡 Tip: This opens your browser for authentication. Once authenticated, credentials are stored in ~/.agiflow/ for future use.

Step 3: Launch Claude Agent

Launch Claude Code with agent-cli session management and model routing:

# Launch Claude with session tracking

agent-cli claude --agent-session-id YOUR_SESSION_ID

ℹ️ No Manual MCP Configuration Needed: agent-cli automatically handles MCP configuration for you. Just authenticate and launch Claude - MCPs are injected dynamically!

✨ Bonus: With agent-cli, you get additional features like session tracking, model routing (switch between Claude, GPT-5, etc.), and task-level progress tracking visible in your Agiflow dashboard.

Verify Connection

After setup with any method, verify the connection by checking available MCP tools:

Open Claude Code's MCP panel (View → MCP Servers)
Look for "agiflow-project-mcp" with a green connection indicator
Verify available tools include: create-task, list-tasks, create-work-unit, etc.

✅ Success! Your Claude Code is now connected to Agiflow. You can create tasks, manage work units, and use scaffolding templates directly from Claude Code.

Troubleshooting

Connection failed or red indicator

Verify your API key is correct and hasn't expired
Check the MCP URL matches your organization and project IDs
Ensure you have an active internet connection
For agent-cli: verify the daemon is running (agent-cli status)
Try refreshing the MCP server connection

Tools not appearing

Restart Claude Code completely (quit and reopen)
Check the mcp_settings.json file has valid JSON syntax
Verify the server isn't disabled in MCP settings
For powertool: ensure environment variables are loaded (echo $AGIFLOW_MCP_PROXY_ENDPOINT)
For agent-cli: check daemon logs (agent-cli logs)

Environment variables not loading (Powertool method)

Make sure you added the export commands to the correct shell config file
Run source ~/.zshrc (or your shell config) to reload
For Claude Code to pick up env vars, you may need to launch it from terminal
On macOS, try adding the variables to ~/.zprofile instead

Next Steps

Project MCP

Learn about all available project management tools and how to use them.

View Documentation

Agent-CLI

Explore session management, model routing, and advanced agent-cli features.

View Documentation

Choose Your Connection Method

Method 1: Marketplace + HTTP MCP (Recommended)

The easiest setup with automatic updates via Claude Code's marketplace. Direct HTTP connection to Agiflow API.

✅ Easiest setup • ✅ Automatic updates • ✅ Simple configuration • ⚠️ Requires internet connection

Method 2: Powertool (stdio MCP)

Use @agiflowai/powertool as a local stdio MCP proxy. Works alongside platform-tools for enhanced capabilities.

✅ Works with platform-tools • ✅ Local proxy control • ℹ️ Requires npm package • ℹ️ Manual configuration

Method 3: Agent-CLI (Local Daemon)

Connect to a locally running agent-cli daemon for advanced session management, model routing, and task tracking.

✅ Full session management • ✅ Model routing • ✅ Task tracking • ℹ️ Requires agent-cli daemon running

{ "mcpServers": { "agiflow-project-mcp": { "type": "http", "url": "https://agiflow.io/api/v1/organizations/YOUR_ORG_ID/projects/YOUR_PROJECT_ID/mcp", "headers": { "X-API-KEY": "your-generated-api-key" } } } }

{ "mcpServers": { "agiflow-project-mcp": { "command": "npx", "args": ["-y", "@agiflowai/powertool", "mcp-serve"], "env": { "AGIFLOW_MCP_PROXY_ENDPOINT": "${AGIFLOW_MCP_PROXY_ENDPOINT}", "AGIFLOW_MCP_API_KEY": "${AGIFLOW_MCP_API_KEY}" } } } }

Verify Connection

After setup with any method, verify the connection by checking available MCP tools:

Open Claude Code's MCP panel (View → MCP Servers)
Look for "agiflow-project-mcp" with a green connection indicator
Verify available tools include: create-task, list-tasks, create-work-unit, etc.

✅ Success! Your Claude Code is now connected to Agiflow. You can create tasks, manage work units, and use scaffolding templates directly from Claude Code.

Troubleshooting

Connection failed or red indicator

Verify your API key is correct and hasn't expired
Check the MCP URL matches your organization and project IDs
Ensure you have an active internet connection
For agent-cli: verify the daemon is running (agent-cli status)
Try refreshing the MCP server connection

Tools not appearing

Restart Claude Code completely (quit and reopen)
Check the mcp_settings.json file has valid JSON syntax
Verify the server isn't disabled in MCP settings
For powertool: ensure environment variables are loaded (echo $AGIFLOW_MCP_PROXY_ENDPOINT)
For agent-cli: check daemon logs (agent-cli logs)

Environment variables not loading (Powertool method)

Make sure you added the export commands to the correct shell config file
Run source ~/.zshrc (or your shell config) to reload
For Claude Code to pick up env vars, you may need to launch it from terminal
On macOS, try adding the variables to ~/.zprofile instead