Factory AI MCP Integration

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:

# Auto-configure
aiwg mcp install factory

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

# 1. Start AIWG MCP server with HTTP transport
aiwg mcp serve --transport http --port 3100

# 2. Expose via tunnel
ngrok http 3100

With Cloudflare Tunnel

# 1. Start AIWG MCP server
aiwg mcp serve --transport http --port 3100

# 2. Expose via Cloudflare
cloudflared tunnel --url http://localhost:3100

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?

# Verify aiwg is in PATH
which aiwg

# Test server manually
aiwg mcp serve

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