Orca MCP Server — Claude Code MCP server
Connects Orca tools to an agent for describing and checking finite-state machines. Useful when topology errors must be found before execution.
claude mcp add --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env ORCA_PROVIDER=<ORCA_PROVIDER> --env ORCA_MODEL=<ORCA_MODEL> --transport stdio mcp-server -- npx -y @orcalang/orca-mcp-serverWhat Orca MCP Server does
Orca MCP Server exposes Orca tools to an agent. The agent can work with finite-state machines described in Markdown and validate their structure before running code. The verifier checks reachability, deadlocks, uncovered state-event pairs, and conflicting guards.
Orca supports states, events, transitions, guards, nested and parallel regions, timeouts, and machine invocation. A machine can be compiled to an XState v5 configuration or a Mermaid diagram. Running the package through npx requires Node 20+; the server uses ANTHROPIC_API_KEY, while one setup variant also passes ORCA_PROVIDER and ORCA_MODEL. The server will not start without ANTHROPIC_API_KEY.
What it helps with
- describe a finite-state machine in Markdown
- detect unreachable states and deadlocks
- check transition coverage and guard determinism
- compile a machine for XState or Mermaid
Example prompts for the agent
- Use the Orca MCP tools to describe a payment-processing state machine in Markdown and verify its topology.
- Check
examples/payment-processor.orca.mdfor deadlocks and unreachable states. - Compile
examples/payment-processor.orca.mdinto an XState configuration.
How to install Orca MCP Server
Platform CLI
claude mcp add --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env ORCA_PROVIDER=<ORCA_PROVIDER> --env ORCA_MODEL=<ORCA_MODEL> --transport stdio mcp-server -- npx -y @orcalang/orca-mcp-serverReplace <…> with your own values
Platform CLI
codex mcp add mcp-server --env ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> --env ORCA_PROVIDER=<ORCA_PROVIDER> --env ORCA_MODEL=<ORCA_MODEL> -- npx -y @orcalang/orca-mcp-serverReplace <…> with your own values
Config file
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@orcalang/orca-mcp-server"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
"ORCA_PROVIDER": "<ORCA_PROVIDER>",
"ORCA_MODEL": "<ORCA_MODEL>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@orcalang/orca-mcp-server"
],
"env": {
"ANTHROPIC_API_KEY": "<ANTHROPIC_API_KEY>",
"ORCA_PROVIDER": "<ORCA_PROVIDER>",
"ORCA_MODEL": "<ORCA_MODEL>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -e ORCA_PROVIDER=<ORCA_PROVIDER> -e ORCA_MODEL=<ORCA_MODEL> mcp-server npx -y @orcalang/orca-mcp-serverReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Orca MCP Server
How do I install Orca MCP Server in Claude Code?
Run claude mcp add orca-mcp-server -e ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY> -- npx -y @orcalang/orca-mcp-server.
What does Orca MCP Server do?
It gives an agent Orca tools for creating and validating finite-state machines. Validation catches structural problems before the machine runs.
What is required to run Orca MCP Server?
Node 20+ and ANTHROPIC_API_KEY are required. The alternative setup command also passes ORCA_PROVIDER and ORCA_MODEL.
