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.
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 | Recommended for current MCP clients |
| HTTP+SSE | https://console.openfactory.tech/mcp/sse | Compatibility for older clients |
| HTTP+SSE messages | https://console.openfactory.tech/mcp/messages | Used automatically by older SSE clients |
Streamable HTTP is the current MCP transport. OpenFactory keeps the older HTTP+SSE endpoints available for clients that have not migrated yet.
Copy-Paste 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) — 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 |
See App Deployment for the full workflow.
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/mcpFor older SSE-only clients, use:
https://console.openfactory.tech/mcp/sseAuthentication 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.