gridctl

<p align="center"> <img alt="gridctl" src="assets/gridctl.png" width="420"> </p> <p align="center"> <strong>MCP gateway with a built-in skill library.</strong> </p> <p align="center"> <em>One YAML. One endpoint. Every MCP server plus the skills you author alongside them.</em> </p> <p align="center"> <a href="https://github.com/gridctl/gridctl/releases"><img src="https://img.shields.io/github/v/release/gridctl/gridctl?include_prereleases&style=flat-square&color=f59e0b" alt="Release"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-f59e0b?style=flat-square" alt="License"></a> <a href="https://github.com/gridctl/gridctl/actions"><img src="https://img.shields.io/github/actions/workflow/status/gridctl/gridctl/gatekeeper.yaml?style=flat-square&label=build" alt="Build"></a> <a href="SECURITY.md"><img src="https://img.shields.io/badge/Security-Policy-f59e0b?style=flat-square" alt="Security Policy"></a> <a href="https://www.bestpractices.dev/projects/12295"><img src="https://www.bestpractices.dev/projects/12295/badge" alt="OpenSSF Best Practices"></a> </p> <p align="center"> <a href="https://devhunt.org/tool/gridctl" title="DevHunt - Tool of the Week"><img src="assets/devhunt.svg" width="200" alt="DevHunt - Tool of the Week, 1st Place"></a> </p>

---

Gridctl aggregates tools from MCP servers into a single gateway and serves Agent Skills as MCP prompts to upstream clients. Define your stack in YAML, apply with one command, and connect Claude Desktop (or any MCP client) through one endpoint.

gridctl apply stack.yaml

Designed for fast, ephemeral, stateless environments, inspired by Containerlab.

⚡️ Why gridctl

MCP servers are everywhere: different transports, different hosting models, different .json files accumulating like dust. Skills are a separate sprawl on top. Switching projects shouldn't mean rewriting every client config.

Gridctl gives you one declarative file for everything you want connected, one local endpoint your client talks to, and a UI that shows you what's actually running. Build fast, throw it away, rebuild it tomorrow.

version: "1"
name: daily

#  Secret set passed in at runtime
secrets:
  sets:
    - dev

network:
  name: daily-net
  driver: bridge

# Global gateway configuration
gateway:
  name: dev
  code_mode: on

# LLM clients auto-linked to this gateway on apply
link:
  - claude
  - claude-code
  - cursor
  - antigravity
  - grok

# Downstream MCP servers behind the gateway
mcp-servers:

  # Jira and Confluence via Atlassian's hosted remote MCP.
  # Authorize once with `gridctl auth login atlassian`; tokens are stored
  # encrypted and refreshed automatically.
  - name: atlassian
    url: https://mcp.atlassian.com/v1/mcp/authv2
    auth:
      type: oauth

  # GitHub repos, issues, and PRs (containerized stdio server)
  - name: github
    image: ghcr.io/github/github-mcp-server:v1.12.1@sha256:0ba840c46a237879c8300e7fddb0b6347f20e029ccb9cbe2ce4a943daa1ff560
    transport: stdio
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${var:GITHUB_PERSONAL_ACCESS_TOKEN}

  # Browser automation and page inspection
  - name: playwright
    command:
      - npx
      - '@playwright/mcp@0.0.80'

  # SaaS app actions through Zapier's hosted MCP endpoint.
  # Same flow: `gridctl auth login zapier` after apply.
  - name: zapier
    url: https://mcp.zapier.com/api/v1/connect
    auth:
      type: oauth

🪛 Install

curl -fsSL https://raw.githubusercontent.com/gridctl/gridctl/main/install.sh | sh

Installs the latest release to ~/.local/bin/gridctl. Full instructions for Homebrew, pre-built binaries, building from source, container runtime setup, and updating/uninstalling are in the Installation guide.

The installer checks SHA256, not release origin. For covered releases, follow Release Verification before extraction or installation, then install the same verified local archive. The guide explains coverage, expected signer and source identity, and the published inventories.

🚦 Quick Start

# Or scaffold your own starter stack.yaml
gridctl init

# Apply the example stack
gridctl apply examples/getting-started/mcp-basic.yaml

# Check what's running
gridctl status

# Open the web UI
open http://localhost:8180

# Clean up
gridctl destroy examples/getting-started/mcp-basic.yaml

🖥️ Connect LLM Application

The easiest way to connect is with gridctl link, which auto-detects installed LLM clients and injects the gateway configuration:

gridctl link              # Interactive: detect and select clients
gridctl link claude       # Link a specific client
gridctl link --all        # Link all detected clients at once

# Local-model clients bog down on large tool lists; link a smaller
# surface via a tool group (or enable gateway code_mode)
gridctl link lmstudio --group <name>

Declaring a link: block in stack.yaml (as above) does the same thing on every gridctl apply: each listed client is linked idempotently once the gateway is healthy, and clients that aren't installed warn and skip. gridctl destroy --unlink removes those entries again.

Already have MCP servers configured in your clients? gridctl import runs the same detection in reverse: it scans those configs (read-only), dedupes the servers it finds, and appends your selection to stack.yaml, offering plaintext secrets into the encrypted variable store on the way.

Supported clients: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini, Antigravity, OpenCode, Grok Build, Continue, Cline, AnythingLLM, LM Studio, Roo, Zed, Goose

<details> <summary>Manual configuration</summary>

Most Applications

{
  "mcpServers": {
    "gridctl": {
      "url": "http://localhost:8180/mcp"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "gridctl": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.14.2", "http://localhost:8180/mcp", "--allow-http"]
    }
  }
}

Restart Claude Desktop after editing. All tools from your stack are now available.

Antigravity

{
  "mcpServers": {
    "gridctl": {
      "serverUrl": "http://localhost:8180/mcp"
    }
  }
}

Antigravity borrows Windsurf's serverUrl field but speaks streamable HTTP, so point it at the /mcp endpoint (not /sse). The IDE and CLI share ~/.gemini/config/mcp_config.json on Antigravity 2.0. Since Antigravity caps each MCP server at 100 tools, pair a large stack with gateway.code_mode: on.

</details>

🎬 Features

Stack as Code

Declarative, version-controlled MCP environments. Validate before you commit, plan before you apply, and detect the moment your environment drifts from what's in version control. Drift detection runs in the background: the canvas flags servers running but absent from your spec, and declarations in your spec that haven't been deployed.

gridctl search postgres        # Find servers in the catalog and the MCP Registry
gridctl add github             # Append a catalog server to stack.yaml by name
gridctl validate stack.yaml    # Lint and schema-check the spec (exit 0/1/2)
gridctl validate stack.yaml --policy policy.yaml  # Offline declaration-policy check
gridctl plan stack.yaml        # Diff against running state
gridctl apply stack.yaml       # Apply the spec
gridctl export                 # Export authored config with references preserved

Export rereads the running deployment's stack file without resolving variables. Recognized inline credentials block export; replace them with authored references and supply values separately on the recipient's host. Review other authored literals before sharing. The Stack spec view's Export YAML action applies the same policy; raw spec content may still contain credentials. See export semantics and migration guidance.

Learn more → Configuration Reference

Generated Python Containers

Build an exact public PyPI release, or a packaged Python project from git or a local directory, without maintaining a Dockerfile. Generated images use pinned Python and uv bases, run as a non-root user, and keep existing host uvx workflows unchanged. In the web UI, choose the Python Package template or the Generated Python source strategy; eligible catalog packages also offer a Run in a container toggle that is off by default.

mcp-servers:
  - name: fetch
    source:
      type: pypi
      package: mcp-server-fetch
      ref: 2026.8.18

  - name: time
    source:
      type: git
      url: https://github.com/modelcontextprotocol/servers.git
      ref: d73f99efbfd40c3aa1b61e88728b3d49fb52608f
      path: src/time
      runtime: python

Learn more → Source configuration · Runnable example · Python runtime base

MCP Execution Controls

Opt into execution.mode: hardened for managed MCP containers, with explicit numeric UID/GID, finite per-replica limits, read-only root, bounded scratch, and no network by default. Required engine and kernel evidence gates routing. Existing server details show execution evidence separately from MCP health.

Local processes can select execution.mode: local for explicit environment inheritance and executable lookup; they remain unsandboxed. Omission retains compatibility behavior. Container observation requires a supported Linux daemon environment; see the guide for runtime limits and acceptance status.

Learn more → Execution controls · Runnable example

gridctl optimize & Usage Observability

Ordinary successful tool dispatches count arguments and results per server, replica, client, and tool. The Metrics workspace charts throughput, call counts, and the savings from output format conversion (measured from the gateway's own before/after counts). Internal sensitive-call handling uses local estimates without payload-bearing observers or client attribution; see counting boundaries. gridctl optimize scans the running gateway and surfaces actionable findings with projected weekly token impact (unused servers, unused tools, schema overhead, and format-conversion shortfalls), plus a paste-ready YAML remediation for each.

gridctl optimize                          # styled findings table
gridctl optimize --format json            # machine-readable OptimizeReport
gridctl optimize --severity warn,critical # narrow to actionable findings

Learn more → Usage Observability

Output Format Conversion

Tool call results default to JSON. Set output_format at the gateway or per-server level to convert structured responses into TOON or CSV before they reach the client, reducing token consumption by 25–61% for tabular and key-value data. Non-JSON responses and payloads over 1 MB are passed through unchanged. A2A envelopes retain atomic JSON and bypass format conversion.

gateway:
  output_format: toon      # Default for all servers: json, toon, csv, text

mcp-servers:
  - name: analytics
    output_format: csv     # Override per server

Learn more → Configuration Reference

Tool Surface Control

A large stack floods the client's context with tools it will never call. Three axes compose: the per-server tools: whitelist narrows what exists, groups: bundle tools across servers behind their own endpoint at /groups/{name}/mcp, and clients: restricts what each linked client may touch.

groups:
  release:
    servers: [github]                      # every tool of these servers
    tools: [gitlab__create_merge_request]  # plus specific