Inistate MCP Server

MCP server for the Inistate platform — module discovery, entry management, and activity submission.

Setup

Environment Variables

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

Install from npm (recommended)

No clone or build needed — npx will fetch and run the published package on demand:

npx -y inistate-mcp

Or install globally:

npm install -g inistate-mcp
inistate-mcp

Interactive setup (recommended)

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:

npx -y inistate-mcp
# or, explicitly:
npx -y inistate-mcp setup

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.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "inistate": {
      "command": "npx",
      "args": ["-y", "inistate-mcp"],
      "env": {
        "INISTATE_API_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Code Configuration

claude mcp add inistate -e INISTATE_API_TOKEN=your-token-here -- npx -y inistate-mcp

Install from source

git clone https://github.com/Inistate/inistate-mcp.git
cd inistate-mcp
npm install
npm run build

Then point your MCP client at node /absolute/path/to/inistate-mcp/build/index.js.

Tools

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)

Resources

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)

Prompts

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)

Modes

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.

Typical Workflow

1. 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)
2. get_module_schema — understand a module's fields, states, and activities
3. get_form — discover required fields before the first submission per (module, activity); reuse its schema for further entries
4. submit_activity — create or update entries (submit_activities for bulk)
5. list_entries — query and browse data (use the fields parameter to keep payloads small)
6. get_entry_history — review entry history

Development

npm run watch          # Watch mode for TypeScript compilation
npm run inspector      # Test with MCP Inspector

MCP Setup

1. Setup

curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

or

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz

2. Verify

mcp-publisher --help

3. Authenticate

mcp-publisher login github

4. Publish: see below

Packaging & Versioning

# Example adding new feature
git checkout -b feat/add-user-tool


# After coding
npx changeset

# Choose:
# 
# minor
# Added new user search tool

# Release
npm run release

# This does:
# install dependencies
# test
# bump version + update changelog + sync server.json
# validate MCP server config
# build (via npm prepare hook)
# publish to npm
# publish to MCP registry

PM2 (Ubuntu/AWS)

Run the HTTP transport in production using PM2:

npm install
npm run build
npm run pm2:start
npx pm2 save

Enable startup on reboot:

sudo npx pm2 startup systemd -u ubuntu --hp /home/ubuntu
npx pm2 save

Common operations:

npm run pm2:restart
npm run pm2:logs
npm run pm2:stop

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.

Testing

Run all tests

npm test

Watch mode (re-runs on file changes)

npm run test:watch

Test structure

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:

• Field type and color validation against the schema
• State color suggestion logic
• Design validation: duplicate names, invalid types/colors/actors, initial state rules, flow integrity, unreachable states, unused activities, AI confidence warnings
• Input normalization: field-type, state-color, and industry aliases; parsing states from a description
• Workflow design: pattern detection (approval, ticket, pipeline, record list), industry defaults

Integration tests verify (no API token needed):

• Mode-gated tool/resource/prompt discovery — runtime mode hides the configure surface, switch_mode reveals and collapses it
• design_workflow, validate_design work end-to-end through the MCP protocol
• Static resources (inistate://schema/runtime, inistate://design-guide) return valid content
• All 4 prompts return correctly templated messages

Interactive testing with MCP Inspector

INISTATE_API_TOKEN=your-token npm run inspector

Opens a browser UI where you can interactively call tools, inspect schemas, and see responses.