Factory AI MCP Integration

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Status: Supported — Factory AI natively supports MCP with both stdio and HTTP transport.

---

Local Setup (stdio)

The simplest configuration — Factory runs the AIWG MCP server as a local process:

Use AIWG to complete this documented outcome: The simplest configuration — Factory runs the AIWG MCP server as a local process
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

This creates `~/.factory/mcp.json`:

{
  "mcpServers": {
    "aiwg": {
      "type": "stdio",
      "command": "aiwg",
      "args": ["mcp", "serve"],
      "disabled": false
    }
  }
}

Project-Level Configuration

For team-shared MCP config, create `.factory/mcp.json` in your project root:

{
  "mcpServers": {
    "aiwg": {
      "type": "stdio",
      "command": "aiwg",
      "args": ["mcp", "serve"],
      "disabled": false
    }
  }
}

Project-level config is lower priority than user-level — personal overrides apply.

---

Remote Setup (HTTP)

For environments where Factory droids execute remotely (cloud sessions, CI), use HTTP transport with a tunnel:

With ngrok

Use AIWG to complete this documented outcome: With ngrok
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

With Cloudflare Tunnel

Use AIWG to complete this documented outcome: With Cloudflare Tunnel
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Configure Factory

{
  "mcpServers": {
    "aiwg": {
      "type": "http",
      "url": "https://your-tunnel-url.ngrok.io",
      "headers": {
        "Authorization": "Bearer ${AIWG_MCP_TOKEN}"
      },
      "disabled": false
    }
  }
}

---

Configuration Schema

Field	Applies To	Description
`type`	Both	`"stdio"` or `"http"`
`disabled`	Both	Boolean toggle (default: `false`)
`disabledTools`	Both	Array of specific tool names to exclude
`command`	stdio	Executable to run
`args`	stdio	Array of arguments
`env`	stdio	Environment variable map (supports `${VAR}` expansion)
`url`	http	Remote endpoint URL
`headers`	http	HTTP headers (e.g., auth tokens)

---

Config File Locations

Level	Path	Priority
User	`~/.factory/mcp.json`	Higher — personal overrides
Project	`.factory/mcp.json`	Lower — team-shared, commit to git

---

MCP Registry

Factory includes a built-in registry of 40+ pre-configured MCP servers:

/mcp

Browse and install servers for:

Category	Examples
Dev Tools	Sentry, Playwright, Hugging Face
Project Mgmt	Notion, Linear, ClickUp, Monday
Payments	Stripe, PayPal
Design	Figma, Canva
Infrastructure	Netlify, Vercel
Data	Airtable, HubSpot, MongoDB

OAuth-based servers use a browser-prompt flow with tokens stored in the system keyring.

---

AIWG MCP Tools Exposed

When connected, Factory droids gain access to AIWG MCP tools:

Tool	Purpose
`discover`	Find AIWG capabilities
`command-run`	Execute allow-listed AIWG CLI commands
`artifact-read`	Read from `.aiwg/` artifact directory
`artifact-write`	Write to `.aiwg/` artifact directory
`template-render`	Render AIWG templates
`agent-list`	List available agents

`workflow-run` has been removed. Use `command-run` for general AIWG CLI execution, or enable `AIWG_MCP_TOOLSETS=flows,missions` for first-class Flow and Mission tools.

---

Troubleshooting

MCP not connecting?

/mcp
# Check AIWG server status — toggle disabled/enabled

Stdio server not starting?

Use AIWG to complete this documented outcome: Stdio server not starting?
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

HTTP transport issues?

# Test tunnel connectivity
curl https://your-tunnel-url.ngrok.io/health

---

Related Resources

• Factory Quick Start — Full AIWG + Factory integration
• Cross-Platform Overview — All provider comparison
• Claude MCP Sidecar — Reference sidecar implementation