Tiny Systems MCP Server

A local Model Context Protocol server that lets AI clients build and deploy Kubernetes workflows by prompt.

No hosted backend. No accounts. Just your kubeconfig and a prompt.

What it does

Tiny Systems is a flow-based workflow engine that runs on Kubernetes. Workflows are CRDs (TinyNode, TinyFlow, TinyProject, TinyScenario) executed by module operators you install via Helm.

This binary exposes Tiny Systems tools to AI clients via the Model Context Protocol. Connect it to Claude Code, Cursor, or any MCP client and ask:

• "Build a Slack bot that alerts when pods enter CrashLoopBackOff"
• "Watch my TLS certificates and warn 30 days before expiry"
• "Scale down non-critical deployments outside business hours"

The AI uses the exposed tools to create CRDs in your cluster. The Tiny Systems operators reconcile them and start running the workflow.

Install

brew install tiny-systems/tap/mcp-server

Or from source:

go install github.com/tiny-systems/mcp-server@latest

Or download a binary from GitHub Releases.

Connect to Claude Code

claude mcp add tinysystems mcp-server serve --namespace <your-namespace>

Then start a conversation:

claude
> Build me a flow that watches pods and sends Slack alerts when they crash

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Architecture

   ┌─────────────────┐
   │  Claude Code /  │
   │  Cursor / any   │
   │  MCP client     │
   └────────┬────────┘
            │ MCP (stdio)
            ▼
   ┌─────────────────┐       ┌──────────────────┐
   │  mcp-server     │──────▶│  Your K8s        │
   │  (this binary)  │ kubectl cluster          │
   └────────┬────────┘       │  TinyNode,       │
            │                │  TinyFlow CRDs   │
            │                └──────────────────┘
            │ HTTPS
            ▼
   ┌──────────────────┐
   │  tinysystems.io  │
   │  /v1/solutions   │
   │  /v1/modules     │
   └──────────────────┘

Two backends: your cluster for flow building (via kubectl), the Tiny Systems public API for solution and module discovery (via HTTPS). The binary is stateless.

Prerequisites

1. A Kubernetes cluster reachable via kubectl
2. Tiny Systems CRDs and at least one module installed:

   helm repo add tinysystems https://tiny-systems.github.io/module/
   helm install tinysystems-crd tinysystems/tinysystems-crd \
     --namespace tinysystems --create-namespace
   helm install common-module tinysystems/tinysystems-operator \
     --namespace tinysystems \
     --set controllerManager.manager.image.repository=<image> \
     --set controllerManager.manager.image.tag=<tag>

   Use search_modules and get_module_info to find available modules and their exact helm install commands.
3. (Optional) otel-collector for trace queries:

   helm install tinysystems-otel-collector tinysystems/tinysystems-otel-collector \
     --namespace tinysystems

If CRDs are not installed, the server returns a clear setup message with the exact helm commands to run.

Tools

Flow building

Tool	Purpose
build_flow	Create a complete flow (nodes + edges + config) in one call
create_flow / delete_flow	Create or delete a flow
add_node / delete_node	Add or remove a node
add_edge / delete_edge	Add or remove an edge
configure_edge	Set edge data mapping with {{$.path}} expressions
configure_node_settings	Set a node's settings
get_node_port_schema	Return the live schema for a placed node's port

Discovery

Tool	Purpose
get_instructions	Returns the full Tiny Systems flow-building guide
list_modules	Lists modules installed in the cluster (TinyModule CRDs)
get_component_info	Returns port schemas for a specific component
search_modules	Search the public module catalog at tinysystems.io/modules
get_module_info	Full module details: components, ports, helm install command
read_project	Returns all flows and nodes in a project

Solutions

Tool	Purpose
search_solutions	Search the public solutions catalog by keyword
get_solution	Full solution details: nodes, edges, settings, configurations
clone_solution	Recreate a solution's nodes, edges, and configurations in the current flow

Observability

Tool	Purpose
send_signal	Trigger a node by sending data to an input port
get_traces / get_trace_detail	Query execution traces via otel-collector

Scenarios

Tool	Purpose
list_scenarios	List sample data snapshots
create_scenario / update_scenario / delete_scenario	Manage scenarios for edge validation

Flags

mcp-server serve [flags]

  --kubeconfig string       Path to kubeconfig (default: $KUBECONFIG or ~/.kube/config)
  --context string          kubectl context to use (default: current-context)
  -n, --namespace string    Kubernetes namespace (default: current context)
  --platform-token string   Developer key for hosted-platform mode (or TINY_PLATFORM_TOKEN)
  --platform-grpc string    Hosted-platform gRPC endpoint (default "https://grpc-api.tinysystems.io")
  --platform-api string     Tiny Systems REST API base URL (default "https://api.tinysystems.io")
  --dev-key string          Developer key for workspace-private solutions and modules
  --otel-service string     otel-collector service name (default "tinysystems-otel-collector")
  --otel-port int           otel-collector gRPC port (default 2345)

Two modes

Kubeconfig (default)

You bring a cluster, the server reads CRDs directly. Authentication is whatever your kubeconfig already has. Trace data comes from a port-forward to the in-cluster otel-collector.

mcp-server serve --namespace tinysystems

Hosted platform — point Claude directly, no binary needed

The platform now serves MCP itself at https://mcp.tinysystems.io/mcp. Skip this binary entirely and paste the URL into your AI client's MCP config:

{
  "mcpServers": {
    "tinysystems": {
      "url": "https://mcp.tinysystems.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-dev-key>"
      }
    }
  }
}

Get a dev key from the dashboard: Settings → Developer Keys, or run through the onboarding wizard at /[workspace]/onboarding which mints one and shows the ready-to-paste snippet.

The old --platform-token mode on this binary still works for backwards compatibility, but prints a deprecation warning. Removal target is a future major release.

Same MCP tool surface in both modes. The wire path differs:

Tool	Kubeconfig mode	Platform mode
list_modules / get_module_info	reads TinyModule CRDs	MCPService.ListModules / GetModule
read_project / list_projects	reads TinyProject CRDs	MCPService.GetProject / ListProjects
create_flow / delete_flow	creates TinyFlow CR	MCPService.CreateFlow / DeleteFlow
edit_flow / build_flow	mutates TinyNode + TinyEdge	MCPService.ApplyFlowOperations
send_signal	creates TinySignal CR	MCPService.SendSignal
get_traces / get_trace_detail	otel-collector port-forward	MCPService.ListTraces / GetTrace
get_node_port_schema	local schema simulation	MCPService.InspectPort
scenarios	TinyScenario CRDs	MCPService.ListScenarios / Create / Update / Delete

Developer key

Without --dev-key, search_solutions and search_modules return only public catalog items. With a dev key, they also include workspace-private solutions and modules owned by the key's workspace.

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

mcp-server serve --dev-key <your-key> --namespace tinysystems

Troubleshooting

"Tiny Systems CRDs are not installed in this cluster" Run the helm commands shown in the error message to install CRDs, then retry.

list_modules returns an empty list No module operators running in the namespace. Use search_modules to find available modules and get_module_info for the helm install command.

get_traces returns "connection refused" The otel-collector is not installed. Install via Helm or skip trace queries.

Claude says the tool is not responding Log output goes to stderr. Check Claude Code's MCP server logs for errors.

License

Copyright 2026 Tiny Systems Limited. Licensed under the Business Source License 1.1. See LICENSE.