A Corezoid plugin that connects the platform to AI coding agents (Claude Code, Codex, AWS Kiro, and any MCP-compatible client) via MCP. The agent gets direct access to Corezoid processes and deep platform knowledge to create, edit, review, and deploy workflows through natural conversation.
Not just an MCP wrapper over the Corezoid API — an AI-Native management layer for the platform.
The plugin bundles a Go MCP server that exposes Corezoid operations as MCP tools and provides specialist skills that teach Claude the platform model and common workflows:
| Skill | Activate with | Covers |
|---|---|---|
corezoid |
"Corezoid", "process", "conv.json" | Full platform overview, all node types, MCP tools |
corezoid-init |
"set up", "login", "pull workspace" | OAuth login, workspace pull, environment setup |
corezoid-logout |
"logout", "sign out", "disconnect", "выйти" | Remove saved Corezoid credentials for the current workspace |
corezoid-create |
"create a process", "new process" | Building processes from scratch |
corezoid-edit |
"edit", "modify", "update" a process | Modifying existing .conv.json files |
corezoid-lifecycle |
"pause/resume process", "move process/folder", "сними с паузы", "перемести процесс" | Explicit, confirm-gated process lifecycle and server-side reparenting |
corezoid-state-diagram-create |
"create state diagram", "build a state machine", "conv_type state" | Building state diagrams from scratch (conv_type: "state") |
corezoid-state-diagram-edit |
"edit state diagram", "add a state", "change transitions" | Modifying existing state diagrams — states, transitions, side effects |
corezoid-review |
"review", "audit", "check" a process | Analysis, dead code, best-practice violations |
corezoid-project-review |
"review project", "audit folder" | Cross-process audit of an entire folder |
corezoid-node-layout |
"arrange nodes", "lay out", "tidy up the diagram", "fix positions", "remove overlaps" | Auto-arrange node x/y into a clean top-to-bottom flow with error handling railed right and no overlaps (positions only) |
corezoid-dashboard-manager |
"create dashboard", "add chart", "visualize metrics" | Dashboards, charts, node metrics, real-time monitoring |
corezoid-process-tech-writer |
"document", "write docs", "describe process" | Markdown docs + enriched JSON with node descriptions |
corezoid-retro |
"retro", "what did we learn", "capture learnings" | End-of-session retrospective: routes learnings to workspace CLAUDE.md, team feedback, settings, or personal memory — with user confirmation |
corezoid-access |
"share", "give access", "create group", "create api key" | Object sharing, user groups, API keys, invites |
corezoid-alias-manager |
"alias", "short name", "rename alias" | Create, list, modify, delete process aliases |
corezoid-variable-manager |
"variable", "env var", "create variable" | Create, list, modify, delete environment variables |
corezoid-api-connector |
"call Corezoid API", "api/2/json", "api_secret_outer" | Processes that call the Corezoid public API |
corezoid-process-optimizer |
"optimize", "reduce tacts", "improve" | Merge nodes, clean data flow, add resilience |
corezoid-describe |
"update description", "add description", "describe this process" | Set or refresh the description of a process, folder, or project |
corezoid-feedback |
"report a bug", "this is broken", "send feedback" | Collect and submit bug reports / improvement requests |
marketplace-publish-validation |
"publish to marketplace", "check before publish" | Pre-publication checklist for Corezoid marketplace |
corezoid-gitcall |
"git call", "gitcall", "run my code", "custom code node", "python/go/php in a process" | Custom code (Python/Go/Java/PHP/JS/…) as a git_call step — parsing, libraries, crypto, attachments; handles the container build on push |
corezoid-git-context |
after a substantial session, "update git context", "sync context" | Analyse session changes and update _ext/docs/*.md in the Corezoid git mirror |
This plugin is not simply an MCP wrapper over the Corezoid API. It is an attempt to build an AI-Native management layer — one that understands process structure, validation rules, and platform conventions deeply enough to create, audit, and deploy workflows through natural conversation.
- Claude Code, Codex, or AWS Kiro installed
- A Corezoid account
From the GitHub marketplace:
claude plugin marketplace add corezoid/corezoid-ai-plugin
claude plugin install corezoid@corezoidOr from a local clone:
git clone https://github.com/corezoid/corezoid-ai-plugin
claude plugin marketplace add ./corezoid-ai-plugin
claude plugin install corezoid@corezoidFrom the GitHub marketplace:
codex plugin marketplace add corezoid/corezoid-ai-plugin
codex plugin add corezoid@corezoidOr from a local clone:
git clone https://github.com/corezoid/corezoid-ai-plugin
codex plugin marketplace add ./corezoid-ai-plugin
codex plugin add corezoid@corezoidNo build step, no extra setup. The MCP server starts automatically on first use.
Telemetry: the plugin collects anonymous usage data (tool name, duration, error type, API hostname) to improve reliability. No tokens, workspace IDs, or process content are ever sent. To opt out:
export COREZOID_ANALYTICS_DISABLED=1 # add to ~/.zshrc or ~/.bashrc to persist
git clone https://github.com/corezoid/corezoid-ai-plugin
cd corezoid-ai-plugin
sh plugins/corezoid/scripts/install-kiro.sh .Open the workspace in Kiro — the corezoid MCP server, skills, and steering are picked up automatically. This also registers the plugin as a Kiro Power (~/.kiro/powers/installed/power-corezoid/), so it stays available in every Kiro workspace, not just this one — restart Kiro (or reload the window) to pick it up.
claude plugin update corezoid@corezoid # Claude Code
codex plugin marketplace upgrade && codex plugin add corezoid@corezoid # CodexCodex 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.
git pull && sh plugins/corezoid/scripts/install-kiro.sh . # AWS KiroRestart Claude Code / Codex after updating to apply the new version.
On the first Corezoid operation Claude detects that no credentials are present for the current working directory and runs the login tool automatically — your browser opens for OAuth2 sign-in and the session continues without interruption.
All credentials plus per-workspace config (account URL, workspace ID, stage ID, cached project ID, git mirror URL) are stored in a single user-level file ~/.corezoid/config.json (mode 0600). Each entry in folders[] is keyed by an absolute root_path; the MCP server picks the longest-prefix match against the current working directory, so sub-agents launched deep in the workspace pick up the right credentials automatically.
You can trigger login manually at any time:
log in to Corezoid
Nothing needs to live in the project tree — secrets (access_token, api_secret) never leave ~/.corezoid/.
{
"version": 1,
"folders": [
{
"root_path": "/Users/you/work/my-corezoid-ws",
"account_url": "https://account.corezoid.com",
"corezoid_url": "https://admin.corezoid.com",
"workspace_id": "12345",
"project_id": 4242,
"access_token": "eyJhbGci...",
"expires_at": "2026-08-09T12:34:56Z",
"api_login": "",
"api_secret": ""
}
]
}On private/on-prem instances where browser OAuth is unavailable, pass API-key credentials to login:
log in with api_login=<login_id> api_secret=<secret>
They are saved to the current Folder in the same ~/.corezoid/config.json.
| Environment variable | Required | Description |
|---|---|---|
COREZOID_WORK_DIR |
No | Absolute path used to pick which entry in folders[] applies. Set automatically by Claude Code / Codex / Kiro from the user's cwd. Only meaningful if the host cannot preserve cwd across MCP subprocess spawn. |
COREZOID_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 |
COREZOID_HTTP_PORT |
No | Activate the Streamable HTTP transport on this port (e.g. 8080). When set the server listens for MCP over HTTP instead of stdio — intended for hosted marketplace deployments. The browser OAuth login flow is not available in HTTP mode, so credentials must come from ~/.corezoid/config.json or from the environment fallback below. |
COREZOID_HTTP_TOKEN |
No | Bearer token required on every request when the HTTP transport is active. Unset does not disable authentication: the server mints a random token at startup and prints it to stderr for you to copy into your client config. Set this to keep the same token across restarts. |
COREZOID_HTTP_ALLOWED_ORIGINS |
No | Comma-separated Origin allowlist for the HTTP transport |
COREZOID_AUTOLAYOUT |
No | Set to off to disable auto-placement of new (0,0) nodes on push-process (default: preserve) |
COREZOID_WS_URL |
No | Override the build WebSocket endpoint used by git_call compilation (on-prem installs) |
COREZOID_INSECURE_TLS |
No | Set to 1 to skip TLS verification — on-prem installs with self-signed certificates only |
COREZOID_DEBUG |
No | Set to 1 for verbose API request/response tracing |
COREZOID_DEBUG_LOG |
No | Path for the MCP-mode log file (default ~/.corezoid/mcp.log) |
Normally every auth value lives in ~/.corezoid/config.json, written by the login tool. For hosts that cannot run the interactive browser login and have no writable config — CI jobs, containers, the Streamable HTTP transport — the same fields can be supplied through the environment:
| Environment variable | Folder field |
|---|---|
COREZOID_ACCOUNT_URL |
account_url |
COREZOID_API_URL |
corezoid_url (base URL only, no /api/2/json suffix) |
COREZOID_APIGW_URL |
apigw_url (default https://api-apigw.corezoid.com) |
COREZOID_WORKSPACE_ID |
workspace_id |
COREZOID_PROJECT_ID |
project_id |
COREZOID_STAGE_ID |
stage_id |
COREZOID_ACCESS_TOKEN |
access_token |
COREZOID_TOKEN_EXPIRES_AT |
expires_at (RFC 3339; omit for a token with no known expiry) |
COREZOID_API_LOGIN |
api_login |
COREZOID_API_SECRET |
api_secret |
COREZOID_GIT_URL |
git_url |
COREZOID_GIT_STAGE_PATH |
git_stage_path |
Precedence rules:
- The config file wins, field by field. A variable is used only where the
folders[]entry matching the current working directory leaves that field empty — or when no entry matches at all. - Credential pairs are merged as a unit, not field by field.
COREZOID_API_LOGINandCOREZOID_API_SECRETare taken together or not at all: Corezoid verifies the request signature against the secret belonging to that login, so a login from the config combined with a secret from the environment can never authenticate — it would only produce an opaque401. Half a pair is refused locally and the reason is reported in the next auth error.COREZOID_ACCESS_TOKENandCOREZOID_TOKEN_EXPIRES_ATare paired the same way, so a fresh token never inherits a stale expiry. - A stored token that has already expired counts as missing, so
COREZOID_ACCESS_TOKENtakes over instead of leaving the server with no credentials. - A rejected variable is reported, not silently dropped. A malformed
*_ID/*_EXPIRES_AT, or half an API-key pair, is named in the auth error the tool returns — so "not authenticated" cannot be mistaken for "never configured". - Environment values are never written back to
~/.corezoid/config.json— an env-supplied field is used in memory only. The server still writes the caches it resolves itself (project_id,git_url,git_stage_path), as it does in a normal setup. logoutcannot remove them — unset the variables to fully deauthenticate.- A minimal working set is
COREZOID_ACCOUNT_URL+COREZOID_STAGE_ID+ eitherCOREZOID_ACCESS_TOKENorCOREZOID_API_LOGIN+COREZOID_API_SECRET. AddCOREZOID_API_URLto skip API-URL discovery. - API-URL discovery runs on the first authenticated operation, not at startup: with a token the API base URL is read from the account's clients endpoint; with API-key credentials — which that endpoint does not accept — it falls back to
COREZOID_ACCOUNT_URL. SetCOREZOID_API_URLexplicitly when the API is not served from the account host, or when the account host is unreachable from where the server runs.
In Claude Code / Codex these can be set in the env block of the corezoid server in your MCP config, or exported in the shell that launches the client.
COREZOID_ACCESS_TOKEN and COREZOID_API_SECRET are secrets. Prefer your CI's secret store over a committed config file — ~/.corezoid/config.json is written with mode 0600, an environment variable inherits whatever protection the host gives it.
The MCP server collects anonymous usage data (tool name, duration, error type, API hostname) to help improve the plugin. Tokens, workspace identifiers, process content, and personal data are never sent.
To opt out, set the environment variable before starting Claude Code:
export COREZOID_ANALYTICS_DISABLED=1See SECURITY.md for the full list of collected fields.
Once installed, just talk to Claude naturally:
Pull my Corezoid workspace and show me what processes are in the Payments folder.
Create a process that calls any weather API, handles errors,
and sends the forecast back to the caller.
Create a folder named "Services" in Corezoid.
Edit the "payment" process — add retry logic on API timeout
with exponential backoff up to 3 attempts.
Edit process with id 1278273 — add retry logic
on API timeout with exponential backoff up to 3 attempts.
Review process ID 2778176 for dead nodes, missing error handlers,
and hardcoded values.
Review the process at 1278273_Business.folder/2778176_payment.conv.json
for dead nodes, missing error handlers, and hardcoded values.
Push the updated payment process to Corezoid and run a test task with
{"amount": 100, "currency": "USD"}.
Audit the entire Payments folder — list all processes, check for
validation errors, and summarize what each process does.
| Tool | Description |
|---|---|
login |
Authenticate via OAuth2 (opens browser) |
logout |
Remove saved credentials |
list-workspaces |
List available workspaces and stages |
list-stages |
List stages in a workspace |
deploy-stage |
Deploy/promote one stage onto another (develop→production); dry-run by default, requires explicit confirm to apply |
set-stage-immutable |
Make a stage read-only (immutable) or editable; immutable stages are the only valid deploy targets; requires explicit confirm |
list-projects |
List folders and processes in a stage |
create-project |
Create a new project (with optional stages) in a workspace |
modify-project |
Update a project's title, short_name and/or description |
delete-project |
Move a project to the recycle bin (Trash) |
show-project |
Show a project's stages and parent folder |
pull-folder |
Export an entire folder/stage to local files |
pull-process |
Export a single process to a .conv.json file |
push-process |
Validate and deploy a .conv.json to Corezoid. Blocks when the graph is structurally invalid, when the server changed since pull (force is the lint override only — the concurrency gate has its own overwrite_server_change), when no rollback point could be taken, or when the file has no pull baseline but the process is already deployed. Every waived gate is reported in the push result |
layout-process |
Auto-arrange node coordinates (waterfall / layered / table-star regions); local, changes only x/y and collapse flags |
lint-process |
Validate process structure locally (no API call) |
run-task |
Send a task to a deployed process |
show-task |
Look up one task by ref and/or task_id — data, node, status (read-only) |
list-node-tasks |
List tasks currently sitting in a node |
list-task-history |
Show task execution history |
get-node-stat |
Return time-series in/out statistics for a node |
delete-task |
Remove a task from a node |
modify-task |
Update task parameters |
create-process |
Create a new empty process in a folder |
create-state-diagram |
Create a new empty state diagram (conv_type "state") in a folder |
create-folder |
Create a new subfolder |
show-folder |
Show folder metadata (title, kind, parent) |
list-folders |
List immediate children of a folder (no disk I/O) |
modify-folder |
Rename a folder or update its description |
delete-folder |
Move a folder to the recycle bin |
delete-process |
Move a process or state diagram to the recycle bin |
pause-process |
Preview and explicitly pause a process so Corezoid rejects new tasks |
resume-process |
Preview and explicitly reactivate a paused/debug process |
move-process |
Preview and explicitly reparent a process without copying or deploying it |
move-folder |
Preview and explicitly reparent a normal folder with hierarchy-cycle protection |
create-alias |
Create a short alias for a process |
create-variable |
Create a Corezoid environment variable |
list-variables |
List a stage's environment variables (secrets masked) |
modify-variable |
Change a variable's value/title/data_type or rename it — dry-run + confirm-gated |
delete-variable |
PERMANENTLY delete a variable (no recycle bin) — dry-run + confirm-gated |
create-dashboard |
Create a new dashboard for visualizing node metrics |
get-dashboard |
Get a dashboard with its charts and series |
add-chart |
Add a chart (column, pie, funnel, table) to a dashboard |
modify-chart |
Modify an existing chart (full series replace) |
get-chart |
Get a single chart with its series data |
set-dashboard-layout |
Save chart positions on a dashboard grid |
share-object |
Grant or revoke access on a process/folder/stage/project for a user, API key or group (use privs="none" to revoke) |
list-shares |
List principals with access to a shared object |
create-group |
Create a new user group (optional description) |
modify-group |
Rename a group or update its description |
list-group-objects |
List processes currently shared with a group |
delete-group |
Delete a user group (refuses by default if shares active; force=true to override) |
add-to-group |
Add a user or API key to a group |
remove-from-group |
Remove a user or API key from a group |
list-groups |
List user groups in the workspace |
create-api-key |
Create a new API key (secret written to ~/.corezoid/api-keys/, never printed in chat) |
modify-api-key |
Rename or re-describe an API key |
delete-api-key |
Delete an API key (invalidates secret immediately) |
list-api-keys |
List API keys in the workspace |
find-principal |
Resolve user / group / API-key name to obj_id |
invite-user |
Invite an external email and share an object in one call |
send-feedback |
Submit feedback about plugin behavior (returns ticket id) |
create-snapshot |
Create a snapshot of the current server state of a process. Also auto-created before push-process overwrites an existing process: if the snapshot call fails the push is blocked, and if the target project/stage cannot be resolved the push is blocked too — both waived by allow_no_snapshot=true on a resolved mutable stage, though retrying a failed call is the safer default. Skipped only where there is nothing to preserve — a process with no deployed version, or an installation whose API has no snapshot object. A push that overwrites live server state without comparing it (overwrite_server_change, or adopt_existing on a file with no baseline) is refused when no snapshot was taken, unless allow_no_snapshot=true is passed as well; a never-deployed process is exempt — it has no previous version to preserve |
list-snapshots |
List all snapshots for a process with version, title, author and creation time |
delete-snapshot |
Delete a snapshot by its obj_id |
get-snapshot |
Get the node list of a specific snapshot for diff comparison |
git-pull-context |
Clone or pull the Corezoid git mirror into .git-context/ |
git-push-context |
Commit and push _ext/ changes to the git mirror |
read-context-file |
Read a file from .git-context/ |
update-context-file |
Write or append to a file inside _ext/ |
When the plugin does something unexpected, the corezoid-feedback skill guides you through collecting a description of the problem and sends it to the Corezoid team via the send-feedback MCP tool.
Privacy guarantees:
- Feedback is sent only after your explicit confirmation. Nothing is sent automatically.
- All fields are scanned for tokens, API keys, JWTs, and long hex secrets before transmission — any matches are replaced with
[REDACTED]. - To disable feedback entirely (e.g. in corporate environments), set
COREZOID_FEEDBACK_DISABLED=1.
Telemetry environment variables:
| Variable | Default | Purpose |
|---|---|---|
COREZOID_ANALYTICS_DISABLED |
— | Opt out of anonymous tool-call telemetry |
COREZOID_ANALYTICS_ENDPOINT |
built-in prod URL | Override analytics endpoint |
COREZOID_ANALYTICS_CONV_ID |
1852976 |
Override analytics conv_id |
COREZOID_FEEDBACK_DISABLED |
— | Disable user-initiated feedback submission |
COREZOID_FEEDBACK_ENDPOINT |
built-in prod URL | Override feedback endpoint |
COREZOID_FEEDBACK_CONV_ID |
1871779 |
Override feedback conv_id |
Claude Code / Codex
└── corezoid MCP server (prebuilt binary)
├── Auth login, logout
├── Workspace list-workspaces, list-stages, list-projects,
│ create-project, modify-project, delete-project, show-project,
│ deploy-stage, set-stage-immutable
├── Processes pull-process, pull-folder, push-process, lint-process, layout-process
│ create-process, create-state-diagram, create-folder,
│ create-alias, create-variable,
│ list-variables, modify-variable, delete-variable,
│ show-folder, list-folders, modify-folder, delete-folder, delete-process
├── Tasks run-task, show-task, list-node-tasks, list-task-history,
│ get-node-stat, modify-task, delete-task
├── Snapshots create-snapshot, list-snapshots, delete-snapshot, get-snapshot
├── Dashboards create-dashboard, get-dashboard, add-chart,
│ modify-chart, get-chart, set-dashboard-layout
├── Access share-object, list-shares,
│ create-group, modify-group, delete-group, list-group-objects,
│ add-to-group, remove-from-group, list-groups,
│ create-api-key, modify-api-key, delete-api-key, list-api-keys,
│ find-principal, invite-user
├── Git context git-pull-context, git-push-context,
│ read-context-file, update-context-file
└── Feedback send-feedback
corezoid-ai-plugin/
├── .claude-plugin/
│ └── marketplace.json # Claude Code marketplace listing (points to plugins/corezoid)
├── .agents/
│ └── plugins/
│ └── marketplace.json # Codex marketplace listing (points to plugins/corezoid)
├── plugins/corezoid/ # Plugin root (skill path token; MCP launcher resolves it per host)
│ ├── .claude-plugin/
│ │ └── plugin.json # Claude Code plugin manifest
│ ├── .codex-plugin/
│ │ └── plugin.json # Codex plugin manifest
│ ├── .mcp.json # MCP server configuration
│ ├── mcp-server/ # MCP server source
│ ├── skills/
│ │ ├── corezoid/ # Universal assistant skill
│ │ ├── corezoid-init/ # Environment setup skill
│ │ ├── corezoid-create/ # Process creation skill
│ │ ├── corezoid-edit/ # Process editing skill
│ │ ├── corezoid-state-diagram-create/ # State diagram creation skill
│ │ ├── corezoid-state-diagram-edit/ # State diagram editing skill
│ │ ├── corezoid-review/ # Process review skill
│ │ ├── corezoid-project-review/ # Project audit skill
│ │ ├── corezoid-node-layout/ # Node auto-layout skill
│ │ ├── corezoid-dashboard-manager/ # Dashboard & chart management skill
│ │ ├── corezoid-process-tech-writer/ # Process documentation skill
│ │ ├── corezoid-process-optimizer/ # Process optimization skill
│ │ ├── corezoid-describe/ # Object description skill
│ │ ├── corezoid-alias-manager/ # Alias management skill
│ │ ├── corezoid-variable-manager/ # Environment variable management skill
│ │ ├── corezoid-api-connector/ # Corezoid public-API caller skill
│ │ ├── corezoid-gitcall/ # git_call custom-code skill
│ │ ├── corezoid-access/ # Sharing, groups, API keys skill
│ │ ├── corezoid-retro/ # End-of-session retrospective skill
│ │ ├── corezoid-feedback/ # Bug / improvement reporting skill
│ │ ├── corezoid-git-context/ # `.git-context/` mirror sync skill
│ │ └── marketplace-publish-validation/ # Marketplace pre-publication checklist
│ ├── docs/ # Node and process documentation
│ └── samples/ # Example .conv.json processes
The MCP server always writes debug output to ~/.corezoid/mcp.log when running in MCP mode. View it with:
tail -f ~/.corezoid/mcp.logIn CLI mode, enable verbose output with:
COREZOID_DEBUG=1 ./convctl pull-process process_id=123See docs/Troubleshooting.md for solutions to common problems:
- Browser did not open during
login - Expired or missing
access_tokenin~/.corezoid/config.json push-processvalidation errors- MCP server startup failures
- Common Corezoid API error codes
| Component | Supported versions | Notes |
|---|---|---|
| Claude Code | ≥ 1.x | MCP protocol 2025-03-26 |
| Codex | current stable | Same MCP server, same skills |
| macOS | 13 Ventura and later | Tested on arm64 and amd64 |
| Linux | Ubuntu 22.04+, Debian 12+ | amd64 tested in CI |
| Windows | not tested | Likely works; PRs welcome |