MCP Integration

OpenFactory supports the Model Context Protocol so AI assistants can help you create builds, inspect recipes, manage VMs, and review test results.

Use MCP when you want to work with OpenFactory from Claude, Cursor, Claude Code, OpenAI Codex, or another MCP-compatible client without switching back and forth between tools.

There are two ways to connect. The Claude and ChatGPT connector signs you in with OAuth and offers the Linux image build and test tools. The API key endpoint, described from Requirements onward, offers more tools, including app testing and deployment, to any MCP client.

Claude and ChatGPT connector

The OpenFactory connector lets Claude and ChatGPT build custom Linux OS images from recipes and test them in virtual machines. Every call acts on the OpenFactory account you signed in with. You never type an API key into a chat, and no tool takes credentials.

Setting	Value
Server URL	`https://console.openfactory.tech/api/mcp-stream/plugin/mcp`
Authentication	OAuth 2.0 authorization code flow with PKCE and dynamic client registration
Scope	`openfactory`
Account	An OpenFactory account at console.openfactory.tech

Connect

Claude: add OpenFactory from the Connectors directory, or open Settings > Connectors, choose Add custom connector and paste the server URL. Claude opens the OpenFactory sign-in and consent page.
Claude Code: run the command below, then run /mcp in Claude Code and choose OpenFactory to sign in.
ChatGPT: add OpenFactory from the ChatGPT apps directory and sign in when it asks.


claude mcp add --transport http openfactory https://console.openfactory.tech/api/mcp-stream/plugin/mcp

Typical workflow

Find a starting recipe with list_recipes and get_recipe, or write one. validate_recipe checks it.
create_build creates the build, and build_image compiles, tests and verifies the image. get_build_status, get_build_evidence and get_test_results report the outcome.
get_verification_session names the test VM and the claims to check. Look at the VM with desktop_screenshot, operate it with desktop_click, desktop_type, desktop_key and desktop_drag, and inspect it with guest_exec and guest_read_file. Record each claim with record_verification_step, then call finish_verification_session.
get_iso_download_url returns the download link for a finished image.

Connector tools

Each tool is marked read-only or not, and tools that stop, overwrite or delete something are also marked destructive. Claude asks you to confirm before it runs a destructive tool. The desktop and guest tools act on OpenFactory test VMs, never on your own computer.

Area	Read-only	Creates or changes	Stops, overwrites or deletes
Recipes and builds	`list_recipes`, `list_recipe_categories`, `get_recipe`, `validate_recipe`, `get_feature_reference`, `query_build_knowledge`, `check_image_inputs`, `list_builds`, `get_build`, `get_build_status`, `get_build_evidence`, `get_build_group`, `get_iso_download_url`, `get_compute_allocation`, `get_harness_skill`	`create_build`, `create_build_from_prompt`, `create_recipe_from_template`, `finalize_build_plan`, `build_image`, `retry_build`, `start_build_group_node`, `request_user_decision`	`update_build_recipe`
Verification and test VMs	`get_verification_session`, `list_test_runs`, `get_test_results`, `get_test_evidence`, `get_test_run_screenshot`, `list_vms`, `get_vm_install_status`, `get_vm_console_url`	`start_verification_session`, `record_verification_step`, `resume_test_environment`, `create_vm`, `start_vm`, `annotate_screenshot`	`finish_verification_session`, `revise_verification_checklist`, `stop_vm`, `delete_vm`
Test VM desktop	`desktop_screenshot`, `desktop_read_region`	`desktop_click`, `desktop_type`, `desktop_key`, `desktop_drag`, `desktop_open_url`, `desktop_close_tab`	None
Screen recordings	`list_recordings`, `get_recording`	`desktop_start_recording`, `desktop_stop_recording`	None
Inside the test VM	`guest_read_file`, `guest_service_status`	None	`guest_exec`, `guest_write_file`, `inspect_boot_sequence`
Installed disk	`summarize_installed_disk`, `list_installed_disk_directory`, `read_installed_disk_file`, `read_installed_disk_journal`	None	None
Labs	`list_labs`, `get_lab`, `get_lab_deployment`, `list_lab_secrets`	`create_lab`, `create_lab_node`, `configure_lab_network`, `ensure_lab_tester`, `deploy_lab_services`, `pause_lab`, `resume_lab`, `generate_lab_secret`, `deliver_lab_secret`	`delete_lab`, `delete_lab_node`, `delete_lab_network`, `delete_lab_secret`
Internal repositories	`list_internal_repositories`	`create_internal_repository`, `attach_internal_repository`, `publish_internal_repository`	`write_internal_repository`
Package builds (Open Build Service)	`get_obs_package_status`, `get_obs_package_log`	`submit_obs_package`	None
Cloud instances	`list_cloud_providers`, `list_cloud_instances`	`test_cloud_provider`, `start_cloud_instance`	`stop_cloud_instance`, `terminate_cloud_instance`, `disconnect_cloud_provider`

Example prompts


Show me the available Debian desktop recipes.


Create a Linux image build draft for my requirements.


Summarize the verification evidence for my latest build.

Your data and access

The connector reads and changes only resources in the OpenFactory account you signed in with. The server checks ownership on every call.
It receives the arguments of each tool call and nothing else. It does not read your chat history, memory or files in Claude or ChatGPT.
Builds, recipes, test evidence, screenshots and recordings you create are stored in your OpenFactory account, the same as work you start in the console.
The privacy policy and terms of service apply.

To revoke access, open Connected clients and choose Disconnect. Access ends at once, and your builds stay in your account. You can also remove the connector in Claude or ChatGPT.

What the connector does not do

The connector does not process payments or transfer money. It does not generate images, audio or video with AI models. It cannot connect cloud accounts, accept secret values or change account settings. Connect cloud accounts in the console.

Support

For questions or problems, use the contact page .

Requirements

An MCP client that supports remote MCP servers
For account-backed access, sign in to OpenFactory in this browser
For guest access, use the generated guest token shown below

Account API keys are shown once when created and can be revoked from the console. Guest tokens are browser identifiers for metered access; they are not account secrets.

Endpoints

Transport	URL	Use
Streamable HTTP	`https://console.openfactory.tech/mcp-stream/mcp`	The OpenFactory MCP endpoint

Streamable HTTP is the only supported transport. The older HTTP+SSE endpoints (/mcp/sse, /mcp/messages) have been retired and now return 410 Gone; point any client still using them at the Streamable HTTP URL above, with the same Authorization header. Claude Code, Claude Desktop, Cursor, Codex, and OpenCode all support Streamable HTTP.

Copy-Paste Config

Preparing your MCP config...

Restart Claude Desktop, Cursor, OpenAI Codex, or any other long-running MCP client after changing its MCP settings. OpenAI Codex reads MCP servers from ~/.codex/config.toml and connects to Streamable HTTP directly: no mcp-remote bridge needed. Claude.ai custom connectors may ask for the server URL and header as separate fields.

Available Capabilities

OpenFactory exposes customer-facing tools for:

Category	Examples
Builds	List builds, create builds from recipes, check build status, retry failed builds
Recipes	Browse templates, validate recipes, customize templates
Images	Get download links for completed artifacts
VMs	List VMs, create test VMs, start or stop VMs, open console links
Tests	Run verification, list test runs, inspect test results, manage reusable test suites
App UI testing	Drive a tester VM to test any app URL: reusable, self-hardening GUI scenarios. No deploy required
App deployment	Deploy a Git repo to a live web app with a public preview URL (`https://<slug>.apps.openfactory.tech`)

Tool availability can vary by plan and organization permissions.

Reusable Test Suites

Test suites can be created before a variant or ISO has been built. Define one or more test cases, custom assertions, predefined tests, and named ISO target slots such as primary, client, or server. When builds are ready, bind each slot to a completed build and run the suite.

Tool	Use
`create_test_suite`	Create a reusable suite without requiring a built variant
`list_test_suites`	List suites available to the current MCP user
`get_test_suite`	View suite definition and recent run history
`update_test_suite_targets`	Bind named ISO target slots to completed builds
`run_test_suite`	Run a suite against bound ISO target slots
`list_test_suite_runs`	List runs created from a suite
`get_test_suite_status`	View authoring readiness and latest run status

App UI Testing: any URL, no deploy

Test the user interface of any web app by pointing a managed tester VM at a URL. You don’t deploy your app with OpenFactory to test it. The tester VM opens a local dev server, a preview/production deployment on Vercel, AWS, Netlify, or any host, or any public URL reachable from the VM. Your app stays where it already runs.

Scenarios are written in plain language and are self-hardening: the first run learns where each UI element is, and later runs replay from that memory (skipping the slow visual pass). That makes replays fast and resilient to small UI changes. Scenarios support environment variables (${VAR}) and 2FA (${totp:VAR}, RFC 6238) for sign-ins; secrets are passed at run time and never stored.

Tool	Use
`ensure_tester_vm`	Get or create your persistent desktop tester VM
`create_app_scenario`	Save a reusable GUI scenario for an app URL
`run_app_scenario`	Run it (pass run-time secrets here) and record screenshots + verdict
`list_app_scenarios` / `get_app_scenario`	Browse scenarios and their hardened cache
`start_app_test` / `record_app_test_step` / `finish_app_test`	Drive and record an ad-hoc run yourself
`annotate_screenshot`	Draw labeled highlight boxes on a screenshot

See App UI Testing for the full workflow, the step schema, and 2FA examples.

App Deployment: Git repo to a public URL

Deploy a web app straight from a Git repository and get a public preview URL (https://<slug>.apps.openfactory.tech) that you can open, share, or point a test scenario at. OpenFactory clones the repo, installs dependencies, starts the app, and health-checks it for you. There’s nothing to wire up: no port forwarding, tunnels, or DNS.

This pairs with App UI testing: deploy your app, then run a scenario against its preview URL, or skip the deploy and test an app you already host (Vercel, AWS, …).

Tool	Use
`create_app`	Register a Git repo as an app (name, source, slug)
`deploy_app`	Deploy the app and return its public preview URL
`list_apps` / `get_app`	Browse your apps, their URLs, and deploy history
`iterate_app`	Dispatch a natural-language change to an app; an agent applies it and redeploys
`get_app_build_status`	Poll an app’s deploy status and in-flight change tickets

See App Deployment for the full workflow. To let your own users speak changes to your app from a mic button, see the Voice Iterate Widget.

Example Prompts


Show my most recent OpenFactory builds and summarize any failures.


Create a Debian server image with SSH, Docker, a deploy user, and default verification tests.


Validate this recipe before I start a build.


Start a VM from my latest completed build and give me the console link.


Create a reusable smoke test suite for example-project with primary and client ISO slots. I will bind the builds later.


Create a smoke-login scenario for my app at https://my-app.vercel.app, run it in a tester VM, and verify the dashboard loads. I'll give you the password and 2FA seed at run time.

Security Notes

Use API keys only with clients you trust.
Revoke old keys from the console when you rotate machines or leave a project.
Prefer approval-required tool permissions for actions that create builds, start VMs, or change infrastructure.
Do not paste OpenFactory API keys into prompts, tickets, public repositories, or shared documents.

Troubleshooting

Tools Do Not Appear

Restart your MCP client and confirm the server URL is exactly:


https://console.openfactory.tech/mcp-stream/mcp

If your client is configured with the retired /mcp/sse URL it will get a 410 Gone: change the URL to the one above; nothing else needs to change.

Authentication Fails

Refresh this page and copy the generated configuration again. Signed-in users should use the generated Authorization header. Guest users should use the generated X-Guest-Id header from the copy-paste config above.

Build or VM Actions Fail

Check your OpenFactory plan, organization permissions, and the build status. Some actions require a completed build, a persistent VM entitlement, or Enterprise permissions.

Transport Errors

Update your MCP client if it does not support Streamable HTTP. If you cannot update it, switch to the HTTP+SSE compatibility endpoint.