Connects the Simulator.Company platform to AI clients to manage actors, graphs, forms, and financial accounts through natural language.
Also known as corezoid/simulator-ai-plugin
- Stars
- 62
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is Simulator.Company MCP?
Simulator.Company connects the Simulator.Company platform to AI clients to manage actors, graphs, forms, and financial accounts through natural language.
Summary generated from the project's README
About Simulator.Company MCP server
Managing complex business simulations and platform entities through natural language is what this MCP server enables for developers using Claude Code, Codex, or AWS Kiro. It connects the Simulator.Company platform directly to your AI client, allowing you to control actors, financial accounts, graphs, and forms without manual API calls. The server acts as a bridge that translates conversational commands into REST API actions, providing specialized skills for everything from designing smart forms to running behavioral simulations.
To use this server, you need a Simulator.Company account and Go 1.27.4+ installed on your system. Authentication is handled via an interactive OAuth2 browser flow or by providing a workspace API key in a .env file. Once connected, you can manage specific workflows like task assignments, meeting scheduling, or even full application generation by analyzing existing processes. The plugin supports various environments, including cloud and local development setups, and maintains session state through local credential storage.
What you can do with it
- 1Automate application generationAsk the AI to build a complete application by analyzing existing processes and designing page maps.
- 2Perform behavioral simulationsRun 'what if' scenarios to forecast outcomes and compare different model behaviors over time.
- 3Manage financial transactionsInstruct the client to record transactions, check account balances, or transfer funds between accounts.
- 4Coordinate team tasksCreate and assign tasks to specific actors or roles like executors and approvers.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ACCESS_TOKENSIMULATOR_ANALYTICS_DISABLEDSIMULATOR_API_BASE_URLSIMULATOR_API_SECRETSIMULATOR_PROFILEWORKSPACE_ID
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecorezoid/simulator-ai-plugin is public and reachablegithub.com/corezoid/simulator-ai-plugin ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/corezoid/simulator-ai-plugin ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSimulator.Company — Claude Code, Codex & Kiro Plugin
Status: stable — released, actively maintained. Supported clients: Claude Code ≥ 1.x, Codex, AWS Kiro. Go 1.27.4+ required. macOS and Linux tested.
A plugin for Claude Code, Codex and AWS Kiro that connects the Simulator.Company platform to Claude via MCP (Model Context Protocol). Claude gets direct access to the Simulator REST API and domain knowledge to manage actors, graphs, forms, and financial accounts through natural conversation.
What it does
The plugin bundles a Go MCP server that exposes the full Simulator.Company public API as MCP tools and provides specialist skills that teach Claude the platform's entity model and common workflows:
| Skill | Activate with | Covers |
|---|---|---|
simulator |
"use Simulator", "call Simulator API" | Full platform overview, all entities, MCP tools |
simulator-init |
"setup", "connect to simulator", "login to simulator" | OAuth login, workspace selection, environment setup |
simulator-skills |
"run skill", "use playbook", "/skill ", "save as skill", "what skills do I have" | Skill registry: discover/run saved playbooks (findSkill/getSkill) and author new ones — the data-driven analogue of these built-in skills |
simulator-graph |
"create actor", "link nodes", "add to layer" | Actors, links, layers, graph traversal, bulk push/pull |
simulator-forms |
"create form", "design template", "Account Template" | Form templates (Account Templates), field classes, system forms |
simulator-actors |
"create a record", "fill in a template", "update actor data" | Actor instances of a form, the data value protocol, search & filter |
simulator-app-generator |
"build an app from these processes", "generate a site from process ids", "turn this API into a smart form" | Whole-app generation: analyse existing Corezoid processes, design the page map, build the Smart Form + bridging middleware, verify end-to-end |
simulator-smart-forms |
"smart form", "CDU", "edit page config", "push smart form" | Smart Form lifecycle, pages, CDU protocol, releases |
simulator-smart-forms-logic |
"add logic to smart form", "wire corezoid to smart form", "/get /send process" | Brief generator for the Corezoid process(es) bound to a Smart Form; delegates to corezoid-create / corezoid-edit; procId binding |
simulator-finance |
"record transaction", "account balance", "transfer funds" | Accounts, transactions, transfers, currencies, counters |
simulator-charts |
"chart", "dashboard", "visualise on layer" | Dashboard charts & time-series visualisation on layers |
simulator-simulate |
"what if", "simulate", "forecast", "compare scenarios" | Behaviour simulation: rules in model time over any layer, scenario comparison, ranges over many runs |
simulator-reactions |
"comment on this actor", "reply", "pin comment" | Reactions: comments / events / approvals / ratings (threaded) |
simulator-chat |
"write a message to user N", "DM", "open a chat with" | Messaging: send a message to a user, p2p/group chats (Events-form actors; messages are comment reactions) |
simulator-tasks |
"create a task", "assign to", "who approves", "needs signature" | Tasks/assignments: an Events-form actor + executor (execute) / approver (sign) / legal signer (ds) roles |
simulator-agents |
"delegate to", "assign this to X", "can X do this", "who/which team should do this", "ask X's agent" | Actor agents: discover an agent by competency (findAgent) — a user twin or any actor with an "# Agent" profile — load it (getAgent), then do the task, find a better executor, or escalate (task / p2p) |
simulator-meetings |
"schedule a meeting", "recurring meeting", "agenda", "join link" | Meetings/video/SIP rooms (Events-form actor, scheduleMeeting): schedule, recurrence, agenda, persistent rooms, public & in-app join links |
simulator-attachments |
"upload a file", "attach document", "rename file" | Files: upload, attach/detach to actors & reactions |
simulator-access |
"share with", "grant access", "who can edit this" | Access rules: grant/revoke view/modify/… on objects |
Requirements
- Claude Code, Codex or AWS Kiro installed
- Go 1.27.4+ available in
PATH(the MCP server runs viago run, no build step needed)
Verify withbrew install golang # macOS sudo apt install golang # Ubuntu/Debiango version. - A Simulator.Company account
Installation
Claude Code
From the GitHub marketplace:
claude plugin marketplace add corezoid/simulator-ai-plugin
claude plugin install simulator@simulator
Or from a local clone:
git clone https://github.com/corezoid/simulator-ai-plugin
claude plugin marketplace add ./simulator-ai-plugin
claude plugin install simulator@simulator
Codex
From the GitHub marketplace:
codex plugin marketplace add corezoid/simulator-ai-plugin
codex plugin add simulator@simulator
Or from a local clone:
git clone https://github.com/corezoid/simulator-ai-plugin
codex plugin marketplace add ./simulator-ai-plugin
codex plugin add simulator@simulator
No build step, no extra setup. The MCP server starts automatically on first use.
AWS Kiro
Kiro has no marketplace command and does not resolve the $CLAUDE_PLUGIN_ROOT token that Claude Code and Codex substitute at skill-load time, so it installs from a local clone via a helper script that copies the plugin into the workspace's .kiro/ and resolves that token to an absolute path:
git clone https://github.com/corezoid/simulator-ai-plugin
cd simulator-ai-plugin
sh plugins/simulator/scripts/install-kiro.sh . # installs into the current dir; pass another workspace-dir instead of `.` to target elsewhere
This writes the MCP entry to <workspace>/.kiro/settings/mcp.json with the plugin path resolved to an absolute path (no reliance on KIRO_PLUGIN_ROOT or workspace layout), symlinks the steering file into .kiro/steering/, and hard-copies each skill into .kiro/skills/<name>/ with $CLAUDE_PLUGIN_ROOT replaced the same way. Open the workspace in Kiro and the MCP server, skills, and steering are picked up automatically. .mcp.kiro.json also self-heals if Kiro loads it directly without the script ever having run — it probes for mcp-server/run.sh next to its workspace-root guess and falls back to plugins/simulator/ when that guess misses. The plugin is also published to kiro.dev/powers — see POWER.md.
Updating
claude plugin update simulator@simulator # Claude Code
codex plugin marketplace upgrade && codex plugin add simulator@simulator # Codex
Codex has no plugin update subcommand — refresh the marketplace snapshot with
codex plugin marketplace upgrade (upgrades all configured Git marketplaces; pass a
name to target one) and re-run codex plugin add to install the refreshed version.
Restart Claude Code / Codex after updating to apply the new version. For AWS Kiro, git pull the clone and re-run plugins/simulator/scripts/install-kiro.sh (it is idempotent) to refresh the workspace overlay.
Authentication
There are two ways to authenticate. The interactive OAuth2 flow below is the default. If you
already hold a workspace API key, put it in .env as SIMULATOR_API_SECRET and skip
straight to API key — the rest of this section does not apply.
Simulator runs on many environments (cloud, on-prem, local dev), so the first step is to
choose one. The set-environment tool takes a cloud preset — mw.simulator.company
(default) or sim.simulator.company — or a custom/local URL (host or full URL; /papi/1.0
is appended if omitted). It fetches that gateway's public config to derive the correct
OAuth account URL — the platform authenticates through the account system, and one account
may back several environments, so the auth URL is determined per gateway rather than fixed.
The chosen API base and account URL are saved to .env (SIMULATOR_API_BASE_URL,
ACCOUNT_URL). Switching environment later clears the token + workspace and requires a fresh
login.
Next Claude runs the login tool — your browser opens for OAuth2 sign-in against the chosen
environment's account URL and the token is saved. Claude then lists your workspaces with
getWorkspaces and lets you pick one by name; set-workspace (by name or accId)
saves the choice as WORKSPACE_ID. You never need to know the workspace id.
The token is saved to .env in your working directory (mode 0600) and reused on every subsequent session. When it expires, the login flow triggers again automatically.
You can also trigger login manually at any time:
log in to Simulator
API key (non-interactive)
For CI, headless runs and service integrations, authenticate with a pre-issued workspace
access key instead of a browser sign-in. Create one at account.corezoid.com → workspace,
then put it in .env alongside the gateway and the workspace it belongs to:
SIMULATOR_API_BASE_URL=https://mw.simulator.company/papi/1.0
SIMULATOR_API_SECRET=your_workspace_key
WORKSPACE_ID=the_key_s_workspace_accId
Every request is then sent as Authorization: Bearer <key>, and the OAuth flow is disabled
end to end: login explains itself instead of opening a browser, no token is written to
.env, and set-environment refuses (the key is scoped to one workspace on one gateway,
so switching environments at runtime would send it to a host it was not issued for — change
.env and restart instead).
The plugin only ever reads SIMULATOR_API_SECRET; it never writes it back to .env, logs
it, or sends it in telemetry. .env is read once at startup, so a restart is required after
editing it. Because the key is long-lived, the server refuses to start if the API base URL
would send it over plaintext HTTP to a non-local host — override with
SIMULATOR_ALLOW_INSECURE_API_SECRET=1 only on a trusted network.
If you get a 401, the error names all three suspects: the key itself, WORKSPACE_ID, and
whether the key belongs to the environment in SIMULATOR_API_BASE_URL.
Static token (optional)
If you prefer to manage the OAuth token yourself, put it in .env:
ACCESS_TOKEN=your_token_here
…or export it in your shell before starting Claude Code, Codex or Kiro:
export ACCESS_TOKEN=your_token_here
.env is not a shell script, so the export keyword belongs only in the second form — a
line like export ACCESS_TOKEN=… inside .env is not an assignment and is skipped. The
same applies to SIMULATOR_API_SECRET.
Precedence is SIMULATOR_API_SECRET > ACCESS_TOKEN > saved OAuth credentials. A static
token is sent as Simulator <jwt>; it is ignored entirely when SIMULATOR_API_SECRET is set.
Configuration
| Environment variable | Required | Description |
|---|---|---|
SIMULATOR_API_SECRET |
No | Workspace API key. When set, every request uses Authorization: Bearer <key>; it overrides ACCESS_TOKEN and saved OAuth credentials, and disables login / set-environment. Never written to .env by the plugin |
ACCESS_TOKEN |
No | Static OAuth token, sent as Simulator <jwt> — overrides saved OAuth credentials; ignored when SIMULATOR_API_SECRET is set |
ACCESS_TOKEN_EXPIRES_AT |
No | Token expiry timestamp (RFC 3339) — written automatically after OAuth login |
ACCOUNT_URL |
No | OAuth account (SA) URL — set automatically by set-environment (derived from the gateway's public config); overrides the default https://account.corezoid.com |
WORKSPACE_ID |
No | Default workspace ID (accId) — set automatically after set-workspace |
SIMULATOR_PROFILE |
No | Environment profile: local | prod (default prod); also via --profile |
SIMULATOR_API_BASE_URL |
No | API base URL — set automatically by set-environment; overrides the profile (e.g. http://localhost:9000/papi/1.0) |
SIMULATOR_ACCOUNT_URL |
No | Override the profile's OAuth account (SA) URL |
SIMULATOR_OAUTH_CLIENT_ID |
No | OAuth2 client ID — on-prem deployments with a custom authorization server should set this to their own client ID; cloud (account.corezoid.com) users do not need it |
SIMULATOR_ALLOW_INSECURE_API_SECRET |
No | Allow SIMULATOR_API_SECRET to be sent over plaintext HTTP to a non-local host. Without it the server refuses to start in that configuration (loopback is always exempt). Parsed as a boolean — 1/true opens it, 0/false/anything unparseable keeps the guard closed |
SIMULATOR_ANALYTICS_DISABLED |
No | Set to any non-empty value to opt out of anonymous tool-call telemetry |
SIMULATOR_ANALYTICS_ENDPOINT |
No | Override the telemetry ingest endpoint (built-in default: the Corezoid team's public analytics process) |
SIMULATOR_ANALYTICS_CONV_ID |
No | Override the telemetry conv_id (default 1852976) |
All values are read from a .env file in the current working directory at startup, and the login / set-workspace tools persist their results back to that file — except SIMULATOR_API_SECRET, which the plugin only ever reads. Because .env is read once at startup, editing it requires a restart.
Telemetry
The MCP server collects anonymous usage data (tool name, duration, error type, API hostname, MCP client name/version) to help the Corezoid team improve the plugin. Tokens, workspace identifiers, and graph/actor/form content are never sent.
To opt out, set the environment variable before starting Claude Code / Codex / Kiro:
export SIMULATOR_ANALYTICS_DISABLED=1
After the first successful login, you are offered a one-time opt-in to include your email address in this telemetry — this is voluntary, declines are always honored, and the choice is stored in ~/.simulator/preferences.json (edit or delete that file to change your answer later).
See SECURITY.md for the full list of collected fields.
Usage
Once installed, just talk to Claude naturally:
Create a business process graph for customer onboarding with three steps:
Document Collection → Review → Approval. Add all steps to a layer.
Create a Car form template with fields: make, model, year, color, VIN.
Add financial accounts: purchase value (USD asset), maintenance costs (USD expense),
and a mileage counter (km).
Record a $450 maintenance transaction on the Toyota Camry actor.
Then show me all accounts and their current balances.
Search for all actors of form type "Task" on the "Main Process" layer.
Pull layer 1a2b3c4d-... to a local YAML, let me edit it, then push it back.
Simulator.Company MCP questions
What clients are supported?
The plugin supports Claude Code (version 1.x or higher), Codex, and AWS Kiro.
How do I authenticate for CI or headless runs?
You can use a workspace access key by placing it in your .env file as SIMULATOR_API_SECRET.
What programming language is required to run the server?
You must have Go version 1.27.4 or higher installed and available in your PATH.