MCP Integration

OpenFactory supports the Model Context Protocol (MCP) , an open standard that lets AI assistants like Claude, Cursor, and other MCP-compatible clients interact directly with OpenFactory. Build OS images, manage VMs, run tests, and browse recipes — all through natural language.

Quick Start

Claude Desktop

Add this to your Claude Desktop configuration (~/.claude/claude_desktop_config.json):


{
  "mcpServers": {
    "openfactory": {
      "url": "https://console.openfactory.tech/api/mcp/sse"
    }
  }
}

Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json):


{
  "mcpServers": {
    "openfactory": {
      "url": "https://console.openfactory.tech/api/mcp/sse"
    }
  }
}

Claude Code


claude mcp add openfactory \
  --transport sse \
  --url "https://console.openfactory.tech/api/mcp/sse"

Claude.ai (Browser)

You can also connect OpenFactory directly in the Claude.ai web app:

Open claude.ai and go to Settings
Navigate to Customize → Connectors
Click the + button to add a new connector
Enter the SSE endpoint: https://console.openfactory.tech/api/mcp/sse
Name it OpenFactory and save

Once connected, you’ll see all 21 OpenFactory tools listed under the connector. Set tool permissions to Needs approval or Always allow based on your preference.

OpenFactory MCP connector configured in Claude.ai settings, showing all 21 available tools

Restart your client and you’ll see OpenFactory’s tools available.

Connection

Property	Value
SSE Endpoint	`https://console.openfactory.tech/api/mcp/sse`
Messages Endpoint	`https://console.openfactory.tech/api/mcp/messages`
Transport	SSE (Server-Sent Events)

The MCP server uses the SSE transport. Your MCP client connects to the SSE endpoint for server-to-client messages and posts to the messages endpoint for client-to-server messages. Most MCP clients handle this automatically.

Your session is tied to your IP address, so your builds, VMs, and test results persist across requests.

Available Tools

OpenFactory exposes 21 tools across 4 categories.

Build Tools

Tool	Description	Key Parameters
`list_builds`	List your builds with status and features	`status_filter`, `limit`
`get_build`	Get full details of a build including its recipe	`build_id`
`get_build_status`	Get current status with stage information	`build_id`
`create_build`	Create a new build from a recipe	`recipe` (name, base_image, features, packages, services, networking, security)
`get_iso_download_url`	Get the download URL for a completed build	`build_id`
`retry_build`	Retry a failed build with the same recipe	`build_id`

Recipe Tools

Tool	Description	Key Parameters
`list_recipes`	Browse pre-built recipe templates	`category`, `search`
`list_recipe_categories`	List all recipe categories with descriptions	—
`get_recipe`	Get full recipe details including packages and services	`recipe_id`
`validate_recipe`	Validate a recipe without starting a build	`recipe`
`create_recipe_from_template`	Customize an existing recipe template	`template_id`, `name`, `modifications`

VM Tools

Tool	Description	Key Parameters
`list_vms`	List your running VMs	`build_id`
`create_vm`	Create and start a VM from a build	`build_id`, `name`, `memory_mb`, `vcpus`
`start_vm`	Start a stopped VM	`vm_name`
`stop_vm`	Stop a running VM (graceful or forced)	`vm_name`, `force`
`delete_vm`	Delete a VM and its resources	`vm_name`
`get_vm_console_url`	Get the VNC console URL for a VM	`vm_name`

Test Tools

Tool	Description	Key Parameters
`run_tests`	Run tests on a built ISO by creating a test VM	`build_id`, `tests`, `memory_mb`, `vcpus`, `timeout_seconds`
`get_test_results`	Get detailed results of a test run	`run_id`
`list_test_runs`	List test runs for your builds	`build_id`, `limit`
`stop_test_run`	Stop a running test and clean up VMs	`run_id`

Examples

Once connected, you can interact with OpenFactory using natural language:

Building an image:

“Build me a Debian Bookworm server with SSH, Docker, and monitoring enabled”

Checking build status:

“Show my recent builds” or “What’s the status of my latest build?”

Running tests:

“Run tests on build abc123” or “Show the test results for my last build”

Working with recipes:

“Show me the available healthcare recipes” or “Create a build from the GxP MedTech template with extra packages: vim, htop”

Managing VMs:

“Create a VM from my latest build” or “List my running VMs”

If you create an account at console.openfactory.tech , you can link your MCP client to it with an API key. This lets you access builds from the web console and keeps your work consistent across different networks and devices.

Creating an API Key

Sign in at console.openfactory.tech
Go to Settings and generate an MCP API key
Add the key to your client config:

Claude Desktop / Cursor:


{
  "mcpServers": {
    "openfactory": {
      "url": "https://console.openfactory.tech/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer of_mcp_your_key_here"
      }
    }
  }
}

Claude Code:


claude mcp remove openfactory
claude mcp add openfactory \
  --transport sse \
  --url "https://console.openfactory.tech/api/mcp/sse" \
  --header "Authorization: Bearer of_mcp_your_key_here"

Managing API Keys

You can also manage keys via the API:


# Create a key
POST /api/mcp-keys
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
 
{"name": "Claude Desktop"}


# List keys
GET /api/mcp-keys
Authorization: Bearer <your_jwt_token>


# Revoke a key
DELETE /api/mcp-keys/{key_id}
Authorization: Bearer <your_jwt_token>

API keys are prefixed with of_mcp_ and shown only once when created. Revoking a key immediately disconnects any clients using it.

Troubleshooting

Connection refused or timeout

Test the connection with:


curl -H "Accept: text/event-stream" \
  https://console.openfactory.tech/api/mcp/sse

You should see SSE events streaming back. If not, the service may be temporarily unavailable.

Tools not appearing

Restart your MCP client after adding the server configuration. Claude Desktop and Cursor may need a full restart to pick up new MCP servers.

”Invalid API key” error

If you’re using an API key, verify it hasn’t been revoked. Remove the Authorization header to fall back to your default session, or generate a new key from the console.

Build or VM operations failing

Check that the operation is valid (e.g., you can only download ISOs from completed builds).