MCP Documentation

Connect AI assistants like Claude, Cursor, and others to STELLWERK via the Model Context Protocol (MCP). Let AI discover, understand, and execute your flows.

Overview

The Model Context Protocol (MCP) is an open standard that enables AI assistants to interact with external tools and data sources. STELLWERK implements MCP to let AI assistants discover, understand, and execute your calculation flows.

What Can AI Do With STELLWERK?

✓ Discover flows – List and explore your available calculation flows
✓ Understand requirements – Learn what inputs each flow needs
✓ Execute calculations – Run flows with data and get results
✓ Review history – Check past executions and their results
✓ Validate formulas – Check formula syntax before using them

Example Conversation

You: "Calculate the shipping cost for a 5kg package to Germany"

AI: Uses STELLWERK to find your shipping-cost flow, checks required inputs, executes it with weight=5 and destination="DE", and returns the result.

Authentication

STELLWERK supports two authentication methods for MCP connections: API Keys for desktop clients and OAuth 2.0 for web-based clients.

Best for desktop AI clients like Claude Desktop, Cursor, and other local applications.

Step 1: Create an API Key

Log in to your STELLWERK account
Navigate to Settings → API Keys
Click Create API Key
Give it a descriptive name (e.g., "Claude Desktop")
Copy the key immediately – it won't be shown again

Step 2: Configure Your AI Client

Add your API key to your AI client's MCP configuration. The key is sent via the Authorization header.

{
  "mcpServers": {
    "stellwerk": {
      "url": "https://stellwerk.io/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Security tip: Use environment variables instead of hardcoding your API key. Most AI clients support ${STELLWERK_API_KEY} syntax.

Tools Reference

STELLWERK exposes the following tools via MCP. AI assistants can call these tools to interact with your flows.

list_flows

List all flows in your tenant. Returns flow names, slugs, descriptions, and status.

Parameters

status	string	Filter by status: active, draft, archived (default: active)
tag	string	Filter by tag slug

Example Response

{
  "flows": [
    {
      "id": "abc-123",
      "name": "Shipping Calculator",
      "slug": "shipping-calculator",
      "description": "Calculate shipping costs",
      "status": "active",
      "nodes_count": 5,
      "tags": ["pricing"],
      "updated_at": "2025-01-14T10:30:00Z"
    }
  ],
  "total": 1
}

get_flow

Get detailed information about a specific flow including its nodes and connections.

Parameters

flow_id *

string

Flow ID (UUID) or slug

Example Response

{
  "flow": {
    "id": "abc-123",
    "name": "Shipping Calculator",
    "slug": "shipping-calculator",
    "status": "active"
  },
  "nodes": [
    { "id": "node-1", "name": "Input", "type": "start", "config": {...} },
    { "id": "node-2", "name": "Calculate", "type": "calculate", "config": {...} }
  ],
  "connections": [
    { "from_node_id": "node-1", "to_node_id": "node-2" }
  ]
}

get_flow_requirements

Get the input requirements for a flow including variable names, types, defaults, and validation rules.

Parameters

flow_id *

string

Flow ID (UUID) or slug

Example Response

{
  "flow": { "id": "abc-123", "name": "Shipping Calculator", "slug": "shipping-calculator" },
  "inputs": [
    { "name": "weight", "type": "number", "required": true },
    { "name": "destination", "type": "string", "required": true },
    { "name": "express", "type": "boolean", "required": false, "default": false }
  ],
  "required_inputs": ["weight", "destination"],
  "optional_inputs": ["express"],
  "example_request": { "weight": 0, "destination": "", "express": false }
}

execute_flow

Execute a flow with the given inputs and return the calculation results.

Parameters

flow_id *	string	Flow ID (UUID) or slug
inputs *	object	Input values for the flow execution

Example Response

{
  "flow": { "id": "abc-123", "name": "Shipping Calculator", "slug": "shipping-calculator" },
  "inputs": { "weight": 5, "destination": "DE", "express": true },
  "outputs": { "cost": 24.99, "delivery_days": 2 },
  "applied_nodes": [
    { "id": "node-1", "name": "Input", "type": "start" },
    { "id": "node-2", "name": "Calculate Base", "type": "calculate" },
    { "id": "node-3", "name": "Output", "type": "end" }
  ],
  "execution_time_ms": 12
}

list_executions

List recent executions for a flow including inputs, outputs, status, and timing.

Parameters

flow_id *	string	Flow ID (UUID) or slug
limit	integer	Max results to return (default: 10, max: 50)
status	string	Filter by status: success, error

Example Response

{
  "flow": { "id": "abc-123", "name": "Shipping Calculator", "slug": "shipping-calculator" },
  "executions": [
    {
      "id": "exec-1",
      "status": "success",
      "duration_ms": 12,
      "input": { "weight": 5 },
      "output": { "cost": 24.99 },
      "created_at": "2025-01-14T10:30:00Z"
    }
  ],
  "total": 1
}

validate_formula

Validate a Dentaku formula for syntax errors. Returns validation status and any error details.

Parameters

formula *

string

The formula to validate

Example Response (Valid)

{
  "valid": true,
  "formula": "price * quantity * (1 - discount)",
  "message": "Formula is valid"
}

Example Response (Invalid)

{
  "valid": false,
  "formula": "price * * quantity",
  "error": "unexpected token: *",
  "message": "Formula has syntax errors"
}

Flow Management

create_flow

Create a new flow. Returns the created flow with its ID and slug.

Parameters

name *	string	Name of the flow
slug	string	URL-friendly identifier (auto-generated if not provided)
description	string	Description of what the flow does
status	string	draft, active, or archived (default: draft)
tags	array	Array of tag names to associate

update_flow

Update an existing flow's properties. Returns the updated flow.

Parameters

flow_id *	string	Flow ID (UUID) or slug
name	string	New name for the flow
description	string	New description
status	string	New status: draft, active, or archived
tags	array	Replace all tags with these tag names

delete_flow

Delete a flow and all its nodes, connections, and test cases. This action cannot be undone.

Parameters

flow_id *	string	Flow ID (UUID) or slug
confirm *	boolean	Must be true to confirm deletion

duplicate_flow

Create a copy of an existing flow including all its nodes and connections. The new flow will be in draft status.

Parameters

flow_id *	string	Flow ID (UUID) or slug of the flow to duplicate
new_name	string	Name for the new flow (default: "Copy of [original]")
new_slug	string	Slug for the new flow (auto-generated if not provided)

Node Management

create_node

Create a new node in a flow. Supported types: start, end, calculate, condition, merge, map, switch.

Parameters

flow_id *	string	Flow ID (UUID) or slug
name *	string	Name of the node
type *	string	Node type: start, end, calculate, condition, merge, map, switch
alias	string	Optional alias for referencing outputs
config	object	Node-specific configuration (formula, condition, etc.)
flow_x, flow_y	number	Canvas position (optional)

update_node

Update an existing node's properties. Returns the updated node.

Parameters

node_id *	string	Node ID (UUID)
name	string	New name for the node
alias	string	New alias (or null to remove)
config	object	New configuration (replaces existing)

delete_node

Delete a node and all its connections from a flow.

Parameters

node_id *

string

Node ID (UUID)

connect_nodes

Create a connection between two nodes. For condition/switch nodes, specify the branch.

Parameters

from_node_id *	string	Source node ID (UUID)
to_node_id *	string	Target node ID (UUID)
branch	string	Branch name for condition nodes ('true'/'false') or switch cases
label	string	Optional label for the connection

disconnect_nodes

Remove a connection between two nodes.

Parameters

connection_id	string	Connection ID - use this OR from/to node IDs
from_node_id	string	Source node ID (UUID)
to_node_id	string	Target node ID (UUID)
branch	string	Required if multiple connections exist between nodes

Testing

create_test_case

Create a test case for a flow with input values and expected output.

Parameters

flow_id *	string	Flow ID (UUID) or slug
name *	string	Name of the test case
input *	object	Input values for the test
expected_output *	object	Expected output values

run_test_case

Run a specific test case and compare the actual output with expected output.

Parameters

test_case_id *

integer

Test case ID

Example Response

{
  "test_case_id": 1,
  "test_case_name": "Basic shipping test",
  "passed": true,
  "expected_output": { "cost": 24.99 },
  "actual_output": { "cost": 24.99 },
  "execution_time_ms": 8
}

run_all_tests

Run all test cases for a flow and return a summary of results.

Parameters

flow_id *

string

Flow ID (UUID) or slug

Example Response

{
  "flow_id": "abc-123",
  "flow_name": "Shipping Calculator",
  "total_tests": 3,
  "passed": 2,
  "failed": 1,
  "all_passed": false,
  "results": [
    { "test_case_id": 1, "test_case_name": "Basic test", "passed": true },
    { "test_case_id": 2, "test_case_name": "Edge case", "passed": true },
    { "test_case_id": 3, "test_case_name": "Failing test", "passed": false, "diff": {...} }
  ]
}

Utilities

list_node_types

List all available node types and their configuration schemas.

Parameters

No parameters required

Example Response

{
  "node_types": [
    {
      "type": "start",
      "name": "Start Node",
      "description": "Entry point of the flow...",
      "config_schema": { "inputs": {...} }
    },
    {
      "type": "calculate",
      "name": "Calculate Node",
      "description": "Performs calculations using Dentaku formulas...",
      "config_schema": { "formula": {...} }
    }
  ],
  "total": 7
}

Integration Guides

Configure your AI assistant to connect to STELLWERK. Each client has its own configuration format.

Claude Desktop

Edit your Claude Desktop configuration file to add STELLWERK as an MCP server.

Config File Location

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration

{
  "mcpServers": {
    "stellwerk": {
      "url": "https://stellwerk.io/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${STELLWERK_API_KEY}"
      }
    }
  }
}

Set Environment Variable

# macOS/Linux - add to ~/.zshrc or ~/.bashrc
export STELLWERK_API_KEY="your_api_key_here"

# Windows PowerShell
$env:STELLWERK_API_KEY="your_api_key_here"

After saving the config, restart Claude Desktop. You should see "stellwerk" in the available tools.

Cursor

Cursor supports MCP servers through its settings. Add STELLWERK to your MCP configuration.

Configuration

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to Features → MCP Servers
Add a new server with the following details:

{
  "name": "stellwerk",
  "url": "https://stellwerk.io/api/v1/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

Other MCP Clients

STELLWERK's MCP endpoint is compatible with any client that supports the Model Context Protocol over HTTP. Use these connection details:

Endpoint	https://stellwerk.io/api/v1/mcp
Method	POST
Protocol	JSON-RPC 2.0
Auth Header	Authorization: Bearer YOUR_API_KEY

Test Connection

curl -X POST https://stellwerk.io/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

Expected Response

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": {
      "name": "stellwerk",
      "version": "1.0.0"
    }
  },
  "id": 1
}

MCP Documentation

Overview

What Can AI Do With STELLWERK?

Example Conversation

Authentication

Step 1: Create an API Key

Step 2: Configure Your AI Client

How OAuth Works

OAuth Details

Tools Reference

list_flows

Parameters

Example Response

get_flow

Parameters

Example Response

get_flow_requirements

Parameters

Example Response

execute_flow

Parameters

Example Response

list_executions

Parameters

Example Response

validate_formula

Parameters

Example Response (Valid)

Example Response (Invalid)

Flow Management

create_flow

Parameters

update_flow

Parameters

delete_flow

Parameters

duplicate_flow

Parameters

Node Management

create_node

Parameters

update_node

Parameters

delete_node

Parameters

connect_nodes

Parameters

disconnect_nodes

Parameters

Testing

create_test_case

Parameters

run_test_case

Parameters

Example Response

run_all_tests

Parameters

Example Response

Utilities

list_tags

Parameters

Example Response

list_node_types

Parameters

Example Response

Integration Guides

Claude Desktop

Config File Location

Configuration

Set Environment Variable

Cursor

Configuration

Other MCP Clients

Test Connection

Expected Response