Simulator Ai Plugin

Simulator.Company — Claude Code & Codex Plugin

[](LICENSE) [](https://go.dev/dl/) [](https://modelcontextprotocol.io) [](https://github.com/corezoid/simulator-ai-plugin/releases) [](https://claude.ai/code)

> Status: stable — released, actively maintained. Supported clients: Claude Code ≥ 1.x, Codex. Go 1.24+ required. macOS and Linux tested.

A plugin for Claude Code and Codex 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-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-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-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-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 or Codex installed
• Go 1.24+ available in PATH (the MCP server runs via go run, no build step needed)

``bash brew install golang # macOS sudo apt install golang # Ubuntu/Debian ` Verify with go 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 install 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 install simulator@simulator

No build step, no extra setup. The MCP server starts automatically on first use.

Updating

claude plugin update simulator@simulator   # Claude Code
codex plugin update simulator@simulator    # Codex

Restart Claude Code / Codex after updating to apply the new version.

Authentication

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

Static token (optional)

If you prefer to manage the token yourself, set it in .env or export it before starting Claude Code or Codex:

export ACCESS_TOKEN=your_token_here

The static token takes priority over saved credentials.

Configuration

| Environment variable | Required | Description | |-------------------------------|----------|-----------------------------------------------------------------------------| | ACCESS_TOKEN | No | Static token — overrides OAuth2 saved credentials | | 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 |

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.

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.

MCP Tools

The MCP server exposes a curated, typed tool set (~95 tools) scoped to the core scenarios — forms, actors, accounts, transactions, graph building, applications/smart forms — rather than the entire REST surface. Each tool maps to a backend operation by its operationId; a drift gate keeps the set in sync with the live /papi/1.0 contract.

Read tools take an optional filter parameter — a comma-separated allow-list of fields to return (e.g. id,title,data.status; dotted paths pick nested data fields). The backend prunes the response to just those fields, so prefer it whenever only part of an entity is needed to keep responses (and token cost) small. Available on every read/lookup/list tool: getActor, getActorByRef, searchActors, searchLayerActors, filterActors, getForm, getForms, searchForms, getAccount, getAccounts, getBalance, getCurrencies, getAccountNames, getTransactions, getTransfer, getRelatedActors, getLinkedActors, getActorLinks, getLayerActors, getEdgeTypes, searchAll, getWorkspaces. (For getLayerActors/searchAll it projects the actor/node items.)

Curated API operations (one tool per backend operation):

| Domain | Tools | |---------------|----------------------------------------------------------------------------------------| | Forms | createForm getForm getForms searchForms updateForm deleteForm setFormStatus createFormAccount getFormAccounts removeFormAccount getLinkedForms getFormsTree | | Actors | createActor getActor getActorByRef searchActors searchLayerActors filterActors updateActor deleteActor setActorStatus getSystemActor getCorezoidProcesses | | Accounts | createAccount getAccount getAccounts getBalance getChildAccounts updateAccount setAccountAmount deleteAccount createAccountPair createCurrency getCurrencies searchCurrencies createAccountName getAccountNames updateAccountName searchAccountNames setAccountFormula getAccountFormula | | Account tags & triggers | saveAccountActors (link Tags/AccountTriggers actors to a pair or one account) getDataFieldActorsByActor saveDataFieldActorsByActor getDataFieldActorsByForm saveDataFieldActorsByForm (data triggers on a data field) | | Counters | saveCounters setCounters getCounters | | Access rules | getAccessRules saveAccessRules getTemplateActorsAccess saveTemplateActorsAccess getTreeLayerAccess saveTreeLayerAccess bulkSaveAccessRules bulkSaveAccountPairsAccessRules requestAccess | | Transactions | createTransaction finalizeTransaction atomCreateTransaction getTransactions getAccountTransactions getTransactionByRef createTransfer createTransferTwoStep getTransfer getTransferByRef filterTransfers | | Graph (links) | createLink massLink getEdge updateEdge deleteEdge existLink deleteEdgesByNodes getEdgeTypes getLayerActors getRelatedActors getLinkedActors getActorLinks manageLayerActors moveActors existLayerElement cleanGraphLayer layerStats | | Reactions | createReaction updateReaction deleteReaction getReactions getReactionsStats markReactionsRead getPinnedReactions togglePinnedReaction | | Attachments | getAttachments getActorAttachments addAttachments updateAttachment removeAttachments uploadBase64 readAttachment (download & read a file's content — text inline, images as a viewable block, PDFs/binary as an embedded resource) | | Search | searchAll (global text/semantic search across actors & users) | | Public links | generatePublicLink getPublicLink revokePublicLink (shareable /m/ join link to an actor — meeting / SIP access without login) | | Meetings | getTranscription (read a meeting call's speech transcription — summarize / extract action items; needs a live room) | | Smart Forms (runtime) | appGetPage appSendForm (drive any Smart Form / CDU app via the get/send page protocol — render a page, submit a form; Corezoid supplies data & control flow. Universal primitives for the simulator-smart-forms-runtime skill) | | Users | getUsers getUser searchUsers (workspace members — resolve a userId/groupId for sharing) | | Setup | set-environment (cloud preset or custom/local URL) login getWorkspaces set-workspace (by accId or name) |

Engine tools (multi-call workflows + client-side computation):

| Tool | Description | |--------------------------|------------------------------------------------------------------------------------------------------| | pullGraphFile | Fetch all actors and edges from a layer and write them to .yaml in the working directory | | pushGraphFile | Read .yaml and sync it with the server layer: create / update / remove to match the file | | getAllLayerPlacements | Return every actor placement on a layer in one paginated call | | compactGraphLayout | Auto-layout a layer into domain-clustered grids (replaces the pull → edit → push loop) | | pruneLongEdges | Delete edges longer than a distance threshold; preserves hierarchy edges | | uploadActorPicture / uploadActorPictureBulk | Set actor pictures from URL / file / base64; auto-rasterise SVG → PNG; bulk dedupes by SHA-256 | | createSmartForm | Create a new Smart Form actor with develop + production environments | | updateSmartFormEnv | Update Corezoid credentials bound to a Smart Form environment (develop or production) | | pullSmartForm | Download all env file trees of a Smart Form to // with .manifest.json | | pushSmartForm | Diff local develop files against .manifest.json, validate, and push changed files in one batch | | deploySmartForm | Deploy one Smart Form env to another (develop → production); creates a new release | | listReleases | List releases for a Smart Form environment | | diffReleases | Show added / removed / modified files between two releases | | rollbackRelease | Roll back to a prior release (forward-only: creates a new active release) | | getFileHistory | List version history for a Smart Form file (fileId from .manifest.json) | | getFileVersion | Fetch the source of one specific file version | | `

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: corezoid
• Source: corezoid/simulator-ai-plugin
• License: MIT
• Homepage: https://simulator.company

Install and usage instructions live in the source repository linked above.