Minicor MCP Server

Build, deploy, and debug VM-based browser and desktop automations from Cursor or Claude Code. The AI agent connects to your Windows VM, writes Python automation scripts, tests them through the Minicor executor, and deploys production-ready workflows — with skills accumulated from every build.

Quick Start

1. Install

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "minicor": {
      "command": "npx",
      "args": ["-y", "@minicor/mcp-server"]
    }
  }
}

Claude Code:

npm install -g @minicor/mcp-server
claude mcp add minicor -- minicor-mcp

2. Authenticate

npx @minicor/mcp-server-setup

Opens a browser to sign in. Tokens stored at ~/.minicor/tokens.json with auto-refresh. For headless: npx @minicor/mcp-server-setup --cli.

3. Bootstrap Workspace (optional)

After cloning a workspace, generate harness-specific config files:

# For Claude Code — creates CLAUDE.md + .claude/settings.local.json
npx @minicor/mcp-server minicor-bootstrap claude-code --dir ./my-workspace

# For Cursor — creates .cursor/rules/workspace.mdc
npx @minicor/mcp-server minicor-bootstrap cursor --dir ./my-workspace

# All harnesses at once
npx @minicor/mcp-server minicor-bootstrap all --dir ./my-workspace

4. Update

npx users: restart your editor (auto-fetches latest). Global: npm update -g @minicor/mcp-server.

Session Lifecycle

The MCP server sends instructions to every client on connect, telling agents to call session_start first when in a workspace clone. This works across all harnesses — Claude Code, Cursor, Bedrock, etc.

Session Tools

| Tool | What it does | | --- | --- | | session_start | Load workspace context (AGENTS.md, VMs, skills, issues, prior session). Call FIRST in a workspace clone. | | session_checkpoint | Save progress mid-session. Writes .minicor/session.json + syncs [Workspace:Session] issue. | | session_end | Persist final state, sync to platform, optionally update context.md. Call before ending work. | | set_workspaces_root | Set default root directory for cloning workspaces (saved to ~/.minicor/config.json). |

Auto-Save on Disconnect

If the agent crashes or the user closes the IDE, the server auto-checkpoints with status: "interrupted" so no session state is lost. The next agent resumes from that checkpoint.

Multi-Agent Handoff

Sessions are synced to [Workspace:Session] issues on the platform, so agents on other machines (or scheduled Bedrock agents) can resume where the last agent left off.

The RPA Lifecycle

This is the complete flow from zero to production automation. The agent handles each phase using MCP tools and skills.

Phase 1: Workspace Setup

"Create a workspace for Acme Corp and set up a VM"

• create_workspace / list_workspaces / get_workspace — create or find a workspace
• vm_list — discover available VMs
• deploy_vm — provision a new Windows VM if needed
• install_mds_on_vm / start_mds_on_vm — install the Minicor Desktop Service
• vm_connect — connect to the VM via Cloudflare tunnel

Phase 2: Clone Workspace

"Clone workspace 257 to my local folder"

• clone_workspace — pulls everything to a local folder:
  • minicor.json — workspace manifest
  • workflows/ — all workflow steps as files (git-native)
  • .minicor/skills/general/ — bundled RPA skills
  • .minicor/skills/workspace/ — workspace-specific learned skills
  • .minicor/issues/ — agent-persisted context from previous runs
  • .minicor/skill-index.json — compact skill summary
  • .minicor/workspace.json — workspace metadata

The folder is git-ready. Push to GitHub for version control, diffs, and CI/CD.

Phase 3: Scope & Research

"I want to automate patient lookup in Centricity"

The agent:

• Takes screenshots, inspects UI elements, identifies the app framework
• Loads relevant skills: get_skill("cdp-browser-automation") or get_skill("desktop-uiautomation")
• Checks list_skills() for customer-specific skills (e.g., "centricity-quirks")
• Studies existing workflows via get_workflow_overview
• Determines strategy: CDP browser, desktop uiautomation, or hybrid

Phase 4: Build (Iterative)

For each automation step:

1. Observe — vm_screenshot + vm_inspect_ui to map the UI
2. Write — Python script using patterns from loaded skills
3. Prototype — vm_execute_script to test on the VM directly
4. Save — create_rpa_flow to persist as a Minicor workflow step
5. Test through Minicor — execute_workflow_async with start_from_step/end_at_step to verify the step works through the real executor (config variables, data passing, JS wrapper)

The testing step is critical — vm_execute_script doesn't resolve {{config.*}} variables or data.input interpolation. The agent loads get_skill("rpa-testing-workflow") for exact tool call sequences.

Phase 5: Test End-to-End

After all steps pass individually:

• execute_workflow_async with real inputs + configurationId — full workflow, no step isolation
• Poll get_execution_status + vm_screenshot to monitor
• diagnose_execution on failure, fix with update_flow, re-run
• Workflow is NOT done until it passes end-to-end through the Minicor executor

Phase 6: Production Hardening

For production workflows (not POCs):

• Load get_skill("state-verification") — add expectedPreState/expectedPostState to each step
• Run the workflow twice to verify idempotency
• create_agent with mode: "monitor" + watchWorkflowId for failure monitoring
• create_agent with mode: "scheduled" + cron for recurring runs
• Persist context: create_issue with [Agent:<name>] Rules for cross-run learning

Phase 7: Extract & Share Knowledge

After a successful build:

• generate_skill — gathers workflow code, execution history, and agent issues
• The agent analyzes patterns and calls save_skill to persist them
• Skills are stored per-workspace and available to future builds
• Customer-specific quirks become reusable knowledge

Skills System

Skills are reusable RPA patterns that accumulate as you build automations. The MCP ships with 6 bundled general skills:

| Skill | Purpose | | ---------------------------- | --------------------------------------------------------------------------------- | | rpa-testing-workflow | Mandatory. Exact tool call sequences for testing through the Minicor executor | | cdp-browser-automation | CDP starter template, React-safe setters, parallel execution | | desktop-uiautomation | Framework selection, element selectors, wait/retry patterns | | data-extraction-strategies | Priority-ordered methods for reading data from screen | | data-passing-between-steps | JS-layer interpolation, config variables, step outputs | | state-verification | LLM-based UI verification for production workflows |

Using Skills

list_skills()                         → see all available skills
get_skill("cdp-browser-automation")   → load full patterns + code templates
save_skill(...)                       → persist a new skill from a successful build
generate_skill(workflowId)            → extract patterns from an existing workflow

Skills Service

Skills are automatically persisted through the Minicor platform API. When authenticated, save_skill and generate_skill store skills server-side so they persist across sessions and are available to other agents in the same workspace.

Skill tiers:

• Global — general RPA knowledge (read-only, bundled with the MCP)
• Per-workspace — learned from agent sessions, persisted across runs
• Customer-specific — app quirks, environment patterns

Without authentication, skills fall back to the bundled .md files in the package.

What You Can Automate

• Web portals — Chrome via CDP. React/Angular SPAs, anti-bot sites, payor portals, EHR web apps.
• Desktop applications — Windows apps via uiautomation, pywinauto, pyautogui. EMR clients, billing software, legacy systems.
• APIs — Direct HTTP when the agent discovers usable endpoints behind a portal.
• Hybrid workflows — Mix browser, desktop, and API steps in one workflow.

VM Setup

The easiest path is to let the agent handle everything:

"Deploy a VM and set it up for automation"

The agent runs: deploy_vm → install_mds_on_vm → start_mds_on_vm → vm_connect

Once the VM is provisioned, a secure tunnel is automatically created. The agent connects via the tunnel URL and is ready to build automations. Chrome instances for browser automation are managed automatically by the MDS — no manual setup needed.

For manual setup, use get_lds_setup_guide for step-by-step instructions.

Tools

VM Tools

| Tool | What it does | | ---------------------- | ------------------------------------------------------------------------------------------ | | vm_list | Discover available VMs (returns ID, name, status, tunnel URL) | | vm_connect | Connect to VM via LDS Cloudflare tunnel URL or VM ID | | vm_disconnect | Disconnect from VM | | vm_status | Health check for the connected VM | | vm_screenshot | Full-screen capture of the VM desktop | | vm_screenshot_region | Zoom into a specific screen area | | vm_execute_script | Run a Python script on the VM | | vm_execution_status | Check status of a running script | | vm_execution_control | Pause, resume, stop, or skip a running script | | vm_inspect_ui | Inspect Windows UI elements (window list, element tree, element at point, focused element) | | vm_read_clipboard | Read VM clipboard contents |

Automation Building

| Tool | What it does | | ----------------------- | --------------------------------------------------------- | | create_rpa_flow | Save a validated Python script as a Minicor workflow step | | debug_rpa_step | Test a script with before/after screenshots | | vm_reset_state | Manage windows: focus app, minimize all, close dialogs | | batch_test_rpa | Run a workflow with multiple test inputs | | replay_execution_step | Re-run a step from a failed execution on the VM | | get_lds_setup_guide | LDS installation walkthrough |

Workflows and Executions

| Tool | What it does | | ---------------------------------------------------------- | --------------------------------------------------- | | create_workflow / update_workflow / delete_workflow | Workflow CRUD | | create_flow / update_flow / delete_flow | Step CRUD | | execute_workflow / execute_workflow_async | Run workflows synchronously or async | | list_executions / get_execution / get_full_execution | View execution history and details | | diagnose_execution | Analyze failures with RPA-specific pattern matching | | get_workflow_overview | Full snapshot: steps, code, recent executions | | test_workflow_step | Run a single step in isolation | | preview_flow_changes / compare_flow_versions | Diff code before deploying |

2FA / OTP

| Tool | What it does | | ----------------------- | ------------------------------------------------------------------------- | | tfa_provision_phone | Buy a Twilio phone number for the workspace (SMS webhook auto-configured) | | tfa_provision_email | Generate a Mailgun email address for OTP capture | | tfa_list_channels | List all provisioned phone numbers and email addresses | | tfa_delete_channel | Remove a channel (releases Twilio number if phone) | | tfa_register_secret | Store a TOTP secret (base32 or otpauth:// URI), encrypted at rest | | tfa_list_secrets | List stored TOTP secrets for the workspace | | tfa_delete_secret | Remove a stored TOTP secret | | tfa_generate_totp | Get the current 6-digit TOTP code + seconds until expiry | | tfa_verify_totp | Verify a TOTP code against a stored secret | | tfa_parse_qr | Parse a QR code image to extract TOTP parameters | | tfa_request_sms_otp | Wait for an SMS OTP (blocks until SMS arrives or timeout) | | tfa_request_email_otp | Wait for an email OTP (blocks until email arrives or timeout) | | tfa_get_challenge | Check the status of a pending challenge | | tfa_resolve_challenge | Manually resolve a challenge (for captchas or Slack-provided codes) | | tfa_cancel_challenge | Cancel a pending challenge |

Workflows that encounter 2FA prompts use these tools to auto-resolve OTP challenges. Provision channels once per workspace, store the IDs in config stores, and reference them with {{config.sms_channel_id}} or {{config.totp_secret_id}} at runtime.

Config Stores

| Tool | What it does | | --------------------------------------------------- | --------------------------------------------------- | | create_config_store | Create a credential store with key-value properties | | list_config_stores / get_config_store | Browse stores | | update_config_property / remove_config_property | Manage individual properties |

Scripts reference credentials as {{config.propertyKey}} — resolved at runtime by the workflow engine.

Issues

| Tool | What it does | | -------------- | ---------------------------------------------- | | list_issues | List all issues in a workspace | | get_issue | Get a specific issue with full description | | create_issue | Create an issue (supports Markdown) | | update_issue | Update title, description, status, or assignee | | delete_issue | Delete an issue |

Agents use Issues to persist context across runs with the [Agent:<name>] title convention:

• [Agent:my-bot] Rules — learned behaviors (e.g., "login page takes 15s to load")
• [Agent:my-bot] Context — persistent state (URLs, credential rotation dates)
• [Agent:my-bot] Session 2026-04-09 — run summaries

Agents

| Tool | What it does | | -------------- | ---------------------------------------------------------------- | | list_agents | List agents in a workspace | | get_agent | Get agent details (task, mode, VM, run stats) | | create_agent | Create an agent (on-demand, scheduled, or workflow monitor mode) |

Agents are autonomous runners that execute tasks on VMs using MCP tools. After building a workflow, the build-rpa-workflow prompt offers to create a monitoring agent that watches for failures and auto-recovers.

Skills

| Tool | What it does | | ---------------- | --------------------------------------------------------------------- | | list_skills | List available skills (filterable by category, tags, workspace) | | get_skill | Load full skill content by name | | save_skill | Save a skill to the skills service and/or local workspace clone | | generate_skill | Gather workflow context for skill extraction (agent writes the skill) |

Workspace Sync

| Tool | What it does | | --------------------------------- | ------------------------------------------------------------------------------ | | clone_workspace | Full workspace clone: workflows + skills + issues + metadata. Defaults to configured workspaces root if outputDir omitted. | | init_project | Scaffold a git-ready project from a workspace (workflows only) | | pull_workflow / push_workflow | Sync individual workflows | | pull_all / push_changed | Bulk sync | | sync_status | Diff local vs deployed | | set_workspaces_root | Set default root directory for cloning workspaces (~/.minicor/config.json) |

Session Lifecycle

| Tool | What it does | | --------------------- | --------------------------------------------------------------------------------------------- | | session_start | Load full workspace context + begin session tracking. Call FIRST in a workspace clone. | | session_checkpoint | Save progress: writes .minicor/session.json + syncs [Workspace:Session] issue. | | session_end | End session: persist final state, sync to platform, optionally update context.md. |

Prompts

| Prompt | What it does | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | build-rpa-workflow | Guided automation building with POC/production mode. Loads skills, iterative build loop, per-step Minicor testing, optional hardening. | | debug-workflow-execution | Analyze a failed execution with VM-aware debugging and replay | | minicor-workflow-guide | Full workflow specification: step types, data access, keywords, libraries | | 2fa-workflow-guide | Handling 2FA in workflows: provisioning channels, TOTP secrets, auto-resolving OTP codes | | workspace-session-guide | Returns AGENTS.md rules and session state for any workspace clone |

The build-rpa-workflow prompt accepts a mode parameter:

• **poc** — Quick prototype. Streamlined testing, no state verification or monitoring.
• **production** — Full hardening. State verification, idempotency testing, monitoring agent, context persistence.
• Omitted — The agent asks the user which mode to use.

Environment Variables

| Variable | Purpose | Default | | -------------------- | ---------------------- | ------------------ | | VM_MANAGER_API_URL | VM Manager service URL | Cloud Run instance |

Auth

• Sign in: minicor-mcp-setup (browser) or minicor-mcp-setup --cli
• Token storage: ~/.minicor/tokens.json
• Auto-refresh: tokens refresh before expiry
• Regions: US (default) or Canada

Development

npm install
npm run build
npm test

Project Structure

src/
  index.ts              — CLI MCP entry (stdio transport, token management, disconnect hooks)
  lib.ts                — Embeddable server factory (in-process, no side effects)
  bootstrap.ts          — CLI to generate harness configs (CLAUDE.md, .cursor/rules, etc.)
  config.ts             — User config (~/.minicor/config.json) — workspacesRoot, etc.
  state.ts              — Shared mutable state (VM connections, active session tracking)
  skills.ts             — Skill loader, parser, index builder
  tools/
    session.ts          — session_start, session_checkpoint, session_end, auto-checkpoint
    skills.ts           — list_skills, get_skill, save_skill, generate_skill
    sync-tools.ts       — clone_workspace, init_project, pull/push, set_workspaces_root
    vm.ts, vm-rpa.ts    — VM and RPA tools
    core.ts             — Workflows, flows, executions
    ...
  prompts/
    workspace-session.ts — Workspace session guide prompt
    build-rpa.ts        — Guided RPA building (POC/production modes)
    ...
skills/
  general/              — Bundled skill files (shipped with npm package)