@rulemate/mcp

Stdio wrapper for RuleMate MCP servers. Connects stdio-only MCP clients like Claude Desktop and Cursor to RuleMate's HTTP MCP endpoints.

What is RuleMate?

RuleMate is a visual configuration platform. It exposes two MCP servers:

• Runner-MCP — execute configuration sessions as an end-user would (configure a product, get a BOM).
• Designer-MCP — design and modify projects via natural language (create nodes, define rules, validate, simulate, publish).

This package is a thin stdio↔HTTP bridge — it does not implement any MCP logic itself. All tools, resources, and prompts come from the RuleMate API.

Installation

You don't need to install it permanently. npx runs it on demand from the npm registry:

npx -y @rulemate/mcp runner
npx -y @rulemate/mcp designer

Claude Desktop — full setup guide

1. Get API keys from RuleMate

Log in to the RuleMate designer as an admin user, then go to Admin → API Keys:

• Tenant key for runner-MCP: section "Tenant keys" → + Generate for tenant → pick a tenant, name the key (e.g. Claude Desktop laptop), set expiration. Copy the rk_... token shown — it appears only once.
• User key for designer-MCP: section "User API keys" → + Generate for user → pick your user, name the key. Copy the rmk_... token.
• Project ID (runner only): open any published project in the designer; the URL …/projects/p_XXX shows the id. It must be among the tenant's allowedProjectIds.

2. Locate the Claude Desktop config file

| OS | Path | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

If the file doesn't exist, create it. It must be valid JSON.

3. Paste this config (replace the placeholders)

{
  "mcpServers": {
    "rulemate-runner": {
      "command": "npx",
      "args": ["-y", "@rulemate/mcp", "runner"],
      "env": {
        "RULEMATE_API_URL": "https://api.rulemate.com",
        "RULEMATE_API_KEY": "rk_paste_your_tenant_key_here",
        "RULEMATE_PROJECT_ID": "p_paste_your_project_id_here"
      }
    },
    "rulemate-designer": {
      "command": "npx",
      "args": ["-y", "@rulemate/mcp", "designer"],
      "env": {
        "RULEMATE_API_URL": "https://api.rulemate.com",
        "RULEMATE_API_KEY": "rmk_paste_your_user_key_here"
      }
    }
  }
}

For local development, swap RULEMATE_API_URL to http://localhost:3001 (or your dev port).

4. Restart Claude Desktop

Fully quit Claude Desktop (Cmd+Q on macOS, right-click tray → Quit on Windows) and reopen it. Config is read at startup; just closing the window is not enough.

5. Verify the connection

In Claude Desktop, open Settings → Developer → Connectors (path may vary by version). You should see:

• rulemate-runner — Connected, N tools (18 expected)
• rulemate-designer — Connected, N tools (17 expected)

In a new conversation, try a prompt that exercises the integration:

"List my RuleMate projects."

Claude should call list_projects from the designer-MCP and show the results. If asked for permission to use the MCP tool, allow it.

Cursor — setup

Same JSON structure under mcpServers in Cursor's MCP config. Cursor recent versions also support HTTP transport directly — see "Direct HTTP" section below if you prefer skipping the wrapper.

Other clients

Any MCP client that spawns processes can use this wrapper. Pass runner or designer as the first CLI argument and provide the env vars below.

Direct HTTP (skip the wrapper)

If your client (back-end agent, custom SDK code, recent Cursor) supports HTTP MCP transport natively, point it directly at the endpoints:

{
  "mcpServers": {
    "rulemate-runner": {
      "type": "http",
      "url": "https://api.rulemate.com/mcp/runner",
      "headers": {
        "Authorization": "Bearer rk_...",
        "X-Rulemate-Project-Id": "p_..."
      }
    }
  }
}

Claude Desktop does not support HTTP transport at time of writing — use the stdio wrapper for it.

Environment variables

| Var | Required by | Notes | |---|---|---| | RULEMATE_API_URL | both | e.g. https://api.rulemate.com or http://localhost:3001 for local dev. No trailing slash. | | RULEMATE_API_KEY | both | rk_... for runner mode, rmk_... for designer mode. Prefix must match mode or you get 401. | | RULEMATE_PROJECT_ID | runner only | The published project the runner session targets. Must be in tenant allowedProjectIds. |

Tools available

Runner-MCP (18 tools)

Session lifecycle (start_session, get_session, delete_session, list_sessions), answering (answer, answer_filter, answer_lookup, select_rows, navigate_iteration, reset_variable, evaluate_formulas, prefill_session), output (get_summary, get_bom, confirm_session), discovery (list_projects, get_project_schema), one-shot (run_headless).

Designer-MCP (17 tools)

Read (10): list_projects, get_project, get_project_summary, search_nodes, get_node, get_rules, list_datasources, get_datasource_schema, validate_project, list_versions.

Write (7): create_project, delete_project (confirm), publish_version, fork_version, start_test_session, simulate_answers, apply_operations (batch graph mutations with tempId resolution).

See the RuleMate MCP docs for the full tool reference, examples, and prompt templates.

Troubleshooting

Claude Desktop says "0 tools" or "Disconnected"

Tail the MCP log to find the cause:

| OS | Log path | |---|---| | macOS | ~/Library/Logs/Claude/mcp-server-rulemate-runner.log (and …-designer.log) | | Windows | %APPDATA%\Claude\Logs\mcp-server-rulemate-*.log | | Linux | ~/.config/Claude/logs/mcp-server-rulemate-*.log |

Common startup errors:

• Missing or invalid tenant API key (expected rk_ prefix) — using rmk_* on runner mode (or vice versa for designer). Check that RULEMATE_API_KEY prefix matches the mode argument.
• Missing X-Rulemate-Project-Id header — runner mode requires RULEMATE_PROJECT_ID env var.
• Error: RULEMATE_API_URL and RULEMATE_API_KEY are required — env vars not passed correctly; check JSON quoting.
• fetch failed: ECONNREFUSED — API not reachable at RULEMATE_API_URL. For local dev, verify pnpm dev:api is running.

Runtime errors during tool calls

• 401 Invalid tenant API key — key was revoked from admin UI, or expired. Generate a new one and update the config.
• 403 Project not allowed for this tenant — RULEMATE_PROJECT_ID is not in the tenant's allowedProjectIds. Update from Admin → Tenants in the designer UI.
• 404 No published version for this project — runner needs at least one published version. Publish the draft from the designer first.

Security notes

• API keys impersonate either the tenant (rk_) or the user (rmk_). Treat them as passwords.
• Soft revoke from Admin → API Keys invalidates the key immediately; subsequent calls return 401.
• All MCP calls are server-side audit logged (apiKeyId, tool, durationMs, success), retained for 30 days.
• Don't commit claude_desktop_config.json to git if your repo is public — it contains tokens.

License

MIT — see LICENSE file.

Links

• Source: https://github.com/virgolus/rulemate/tree/main/packages/mcp-stdio
• RuleMate: https://rulemate.com
• MCP spec: https://modelcontextprotocol.io