Install Tiny Systems

One binary, stdio transport, works with any MCP client.
Connects your AI assistant to your Kubernetes cluster.

Install the MCP server

Homebrew (macOS / Linux)

brew install tiny-systems/tap/mcp-server

Go install

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

Binary download

Grab a prebuilt binary from GitHub Releases (macOS / Linux, amd64 / arm64).

Verify the install:

mcp-server --help

Connect to your AI client

Claude Code

One command:

claude mcp add tinysystems mcp-server serve

This uses your current kubectl context and namespace. To target a specific namespace:

claude mcp add tinysystems mcp-server serve \

--namespace my-namespace

Verify with claude then /mcp — you should see tinysystems with status "connected".

Manual JSON config

Add to ~/.claude.json:

json

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

Claude Desktop

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

json

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

Restart Claude Desktop after editing.

Cursor

Settings → MCP Servers → Add:

json

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

Windsurf

json

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

Any MCP client

The server uses stdio transport (JSON-RPC over stdin/stdout). Spawn the binary with:

command: mcp-server

args: ["serve"]

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

Configuration

Flag	Default	Description
--namespace, -n	current context	Kubernetes namespace to operate in
--context	current context	kubectl context to use (from kubeconfig)
--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 for trace queries
--otel-port	2345	otel-collector gRPC port

Multi-cluster setup

If you work with multiple Kubernetes clusters, use --context to target a specific one. Without it, the server uses your current kubectl context.

List your contexts

kubectl config get-contexts

Register one server per cluster

You can register multiple MCP servers in your AI client, each pointing to a different cluster:

# Production cluster (GKE)

claude mcp add tinysystems-prod mcp-server serve \

--context gke_myproject_us-central1_prod-cluster \

--namespace production

# Staging cluster (EKS)

claude mcp add tinysystems-staging mcp-server serve \

--context arn:aws:eks:eu-west-1:123456:cluster/staging \

--namespace staging

JSON config (multi-cluster)

json

{
  "mcpServers": {
    "tinysystems-prod": {
      "type": "stdio",
      "command": "mcp-server",
      "args": [
        "serve",
        "--context",
        "gke_myproject_us-central1_prod-cluster",
        "--namespace",
        "production"
      ]
    },
    "tinysystems-staging": {
      "type": "stdio",
      "command": "mcp-server",
      "args": [
        "serve",
        "--context",
        "arn:aws:eks:eu-west-1:123456:cluster/staging",
        "--namespace",
        "staging"
      ]
    }
  }
}

Tip: Name your MCP servers descriptively (tinysystems-prod, tinysystems-staging) so you can tell the AI which cluster to work with.

Developer key (optional)

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

claude mcp add tinysystems mcp-server serve \

--namespace tinysystems \

--dev-key YOUR_KEY_HERE

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

Troubleshooting

"Tiny Systems CRDs are not installed in this cluster"

The cluster doesn't have Tiny Systems CRDs yet. Run the helm commands shown in the error message to install the module SDK.

"Failed to connect" in Claude Code

Run "claude mcp list" to check status. 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), "aws eks get-token" (EKS), or the equivalent for your provider.

Empty list_modules result

No modules installed in the namespace yet. Use search_modules to find modules in the public catalog and get_module_info for the helm install command.

Wrong cluster / namespace

Use --context and --namespace flags to target the correct cluster. Run "kubectl config get-contexts" to see available contexts.

Ready to go?

View on GitHub Read the docs