MCP Server Setup

The Tiny Systems MCP server exposes flow-building tools to any AI client that supports the Model Context Protocol. This guide covers setup for every major client.

Install

brew install tiny-systems/tap/mcp-server

Verify:

mcp-server --help

Claude Code

The simplest setup — one command:

claude mcp add tinysystems mcp-server serve --namespace tinysystems

Verify it's connected:

claude
/mcp

You should see tinysystems with status "Connected".

Manual JSON config

If you prefer to edit the config file directly, add to ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "tinysystems": {
      "type": "stdio",
      "command": "mcp-server",
      "args": ["serve", "--namespace", "tinysystems"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS:

{
  "mcpServers": {
    "tinysystems": {
      "command": "mcp-server",
      "args": ["serve", "--namespace", "tinysystems"]
    }
  }
}

Restart Claude Desktop. The Tiny Systems tools appear in the tool picker at the bottom of the composer.

Cursor

Add to your Cursor MCP settings (Settings → MCP Servers → Add):

{
  "mcpServers": {
    "tinysystems": {
      "command": "mcp-server",
      "args": ["serve", "--namespace", "tinysystems"]
    }
  }
}

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "tinysystems": {
      "command": "mcp-server",
      "args": ["serve", "--namespace", "tinysystems"]
    }
  }
}

Any MCP client

The server uses stdio transport (JSON-RPC over stdin/stdout). Any MCP-compatible client can connect by spawning the binary:

command: mcp-server
args: ["serve", "--namespace", "<your-namespace>"]

Log output goes to stderr so it doesn't interfere with the protocol stream.

Flags

Flag	Default	Description
--namespace, -n	Current context's namespace	Kubernetes namespace to operate in
--context	Current kubectl context	kubectl context to use — set this if you have multiple clusters configured
--kubeconfig	$KUBECONFIG or ~/.kube/config	Path to kubeconfig file
--dev-key	(none)	Developer key for workspace-private solutions and modules
--platform-api	https://api.tinysystems.io	Tiny Systems API base URL
--otel-service	tinysystems-otel-collector	otel-collector service name
--otel-port	2345	otel-collector gRPC port

If kubectl config get-contexts lists more than one context, pass --context explicitly so the MCP server doesn't pick up whichever happens to be current.

Developer key (optional)

Without --dev-key, the MCP server can search public solutions and modules from the Tiny Systems catalog. With a developer key, it also sees workspace-private items.

Get a key from the Tiny Systems platform: Settings → Developer Keys.

claude mcp add tinysystems mcp-server serve \
  --namespace tinysystems \
  --dev-key YOUR_KEY_HERE

Or in JSON config:

{
  "mcpServers": {
    "tinysystems": {
      "type": "stdio",
      "command": "mcp-server",
      "args": [
        "serve",
        "--namespace", "tinysystems",
        "--dev-key", "YOUR_KEY_HERE"
      ]
    }
  }
}

Troubleshooting

"Tiny Systems CRDs are not installed in this cluster" The cluster doesn't have Tiny Systems CRDs. Run the helm commands shown in the error message.

"Failed to connect" in Claude Code Run claude mcp list to check. If the binary isn't on PATH, use the full path: /opt/homebrew/bin/mcp-server.

"exec plugin didn't return a token" Your kubectl credentials expired. Run gcloud auth login (GKE) or the equivalent for your cloud provider, then retry.

Empty list_modules result Either no modules are installed in the namespace, or the MCP server is reading the wrong cluster. If kubectl get tinymodule -n <namespace> shows modules but the MCP returns empty, your default kubectl context isn't the one with Tiny Systems installed — re-add the MCP server with an explicit --context=<name>. Otherwise use search_modules to find modules in the public catalog and get_module_info for the helm install command.

Tools available

The MCP server exposes 25 tools. See the full tool reference in the README.

Key tools:

Tool	What it does
build_flow	Create a complete flow (nodes + edges + config) in one call
list_modules	List modules installed in your cluster
search_modules	Search the public module catalog
search_solutions	Find ready-to-deploy workflow patterns
get_component_info	Get port schemas for a specific component
send_signal	Trigger a flow by sending data to a node's input port
get_traces	Query execution traces for debugging