The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Inistate MCP listing page.
MCP server for the Inistate platform — module discovery, entry management, and activity submission.
| Variable | Required | Default | Description |
|---|---|---|---|
INISTATE_API_TOKEN | Yes | — | Bearer token for Inistate API authentication |
INISTATE_API_BASE | No | https://api.inistate.com | API base URL |
INISTATE_MCP_MODE | No | configure | Initial mode: runtime, configure, or frontend (see Modes) |
INISTATE_MCP_NO_SETUP | No | — | Set to 1 to force server mode from a terminal (skip the interactive wizard) |
INISTATE_DEBUG_FILE | No | — | Set to 1 to log write-path tool calls to ./debug.log, or to a path to log there. Off by default; logs identifiers only, never field values |
No clone or build needed — npx will fetch and run the published package on demand:
Or install globally:
Run the binary in a terminal with no MCP client attached and it walks you through entering your API token and picks the right config file for your client:
Supported clients: Claude Desktop, Claude Code (global or project-local .mcp.json), Cursor, Windsurf, Codex CLI, VS Code (user profile or workspace .vscode/mcp.json), Cline, Gemini CLI (global or workspace). Pick "Print config only" to get a JSON block to paste anywhere else.
The wizard only runs when stdin is a TTY (i.e., you launched it yourself). When an MCP client spawns the binary via piped stdio, it skips the wizard and runs as a normal MCP server — set INISTATE_MCP_NO_SETUP=1 if you need to force server mode from a terminal.
Add to your claude_desktop_config.json:
Then point your MCP client at node /absolute/path/to/inistate-mcp/build/index.js.
Tools marked (configure) are only exposed in configure mode — see Modes. Tools the active backend cannot serve (e.g. scaffold_module on the hosted Platform) stay registered but return a structured capability message instead of failing silently.
| Tool | Description |
|---|---|
list_workspaces | List workspaces the user has access to |
set_workspace | Set the active workspace |
list_modules | List all discoverable modules in the workspace |
get_module_schema | Get the canvas schema (basic or extended tier) — available in every mode |
get_module_canvas | Get full module definition with stable IDs (round-trippable) (configure) |
list_entries | Query entries with filters, sorting, and pagination |
get_entry | Read a single entry by ID |
get_form | Get form fields and defaults for an activity |
submit_activity | Create, edit, delete, or run custom activities |
submit_activities | Bulk variant — same activity applied to up to 100 entries in one call |
get_entry_history | Get entry audit trail and comments |
request_upload_url | Default upload path — get a presigned S3 URL to PUT file bytes to |
confirm_upload | Confirm a presigned upload completed; returns the File/Image field path |
upload_file | Fallback upload via base64/multipart (use only if the presigned flow fails) |
download_file | Download a file (returns pre-signed URL) |
design_workflow | Generate a scaffolded module template from a description (configure) |
validate_design | Validate a module schema before creating or updating (configure) |
create_module | Create a new module with schema (configure) |
update_module | Update an existing module's schema (configure) |
scaffold_module | Draft a module schema from existing data (SQLite, Notion, or Airtable table) (configure) — served by the local runtime (inistate-core); on the hosted Platform backend it returns a capability message pointing to design_workflow |
switch_mode | Switch the active mode (runtime / configure / frontend) |
| URI | Description |
|---|---|
inistate://modules | List all modules |
inistate://modules/{name}/canvas | Basic module schema (fields + states) |
inistate://modules/{name}/canvas/extended | Extended schema with activities and flows |
inistate://guardrails | Server-enforced submit_activity rules (read once per session) |
inistate://schema/runtime | Runtime schema — entry/activity/file types and filter operators (default) |
inistate://schema/configure | Module-design schema — write format, field types, colors (configure) |
inistate://design-guide | FACTS Module Design Guide (configure) |
inistate://frontend-guide | REST API reference for hand-written UIs (frontend) |
| Prompt | Description |
|---|---|
design_factsops_workflow | Guide an agent through designing a complete workflow module (configure) |
execute_activity | Guide an agent through executing a specific activity |
diagnose_entry | Guide an agent through investigating an entry's state and history |
modify_module | Guide an agent through modifying an existing module's schema (configure) |
The server exposes a focused tool/resource surface depending on the active mode, keeping agent context lean. Use switch_mode to change it, or set the initial mode via the INISTATE_MCP_MODE env var (default: configure).
| Mode | Surface |
|---|---|
runtime | Entry and activity operations only — querying, reading, submitting, files, history. The leanest surface for using existing modules. |
configure | Everything in runtime plus the module-design tools, resources, and prompts (marked (configure) above). |
frontend | Everything in configure plus the inistate://frontend-guide resource for building hand-written UIs against the REST API. |
Tools and resources marked (configure) / (frontend) are absent from the tool list in narrower modes — switch modes to reveal them.
list_workspaces → set_workspace — select a workspace (auto-selected when exactly one matches; both return the workspace's module list, so list_modules is only needed to refresh)get_module_schema — understand a module's fields, states, and activitiesget_form — discover required fields before the first submission per (module, activity); reuse its schema for further entriessubmit_activity — create or update entries (submit_activities for bulk)list_entries — query and browse data (use the fields parameter to keep payloads small)get_entry_history — review entry historyor
Run the HTTP transport in production using PM2:
Enable startup on reboot:
Common operations:
Set required environment variables (INISTATE_API_TOKEN, and optionally INISTATE_API_BASE, INISTATE_WORKSPACE_ID, OAUTH_ISSUER_URL, INISTATE_APP_URL) in your shell, PM2 ecosystem env, or deployment secret manager before starting.
Tests are in src/ alongside the source files and use Vitest:
| File | Type | What it covers |
|---|---|---|
src/schema.test.ts | Unit tests (76) | designWorkflow, validateDesign (including platform parity and input normalization), helper functions (isValidFieldType, isValidColor, isValidActor, suggestColorForState) |
src/activity-guard.test.ts | Unit tests (42) | submit_activity guard rules — human/hybrid actor, state-change confirmation, confidence-inflation, reference-shape validation |
src/tools.schema.test.ts | Unit tests (19) | Tool input-schema shapes and validation |
src/backend-capabilities.test.ts | Unit tests (9) | Capability gating — tools the active backend cannot serve return a capability message |
src/flagged-annotation.test.ts | Integration tests (5) | Flagged-response annotation — suppressed transitions are explained (flag_reason + agent_action) so agents stop retrying with higher confidence |
src/server.test.ts | Integration tests (17) | Spins up the MCP server as a child process and exercises it through the official MCP SDK client — mode-gated tool/resource/prompt discovery, switch_mode, resource reads, prompt retrieval, and local tool calls |
Unit tests cover:
Integration tests verify (no API token needed):
switch_mode reveals and collapses itdesign_workflow, validate_design work end-to-end through the MCP protocolinistate://schema/runtime, inistate://design-guide) return valid contentOpens a browser UI where you can interactively call tools, inspect schemas, and see responses.