gridctl

Summary

gridctl is an open-source mcp-tooling utility that aggregates multiple MCP servers into a single gateway and serves Agent Skills as MCP prompts to upstream clients. It is licensed under Apache 2.0 and runs as a command-line tool used by platform engineers for defining and applying entire stacks via a YAML file. Its documentation positions it alongside Containerlab, and it focuses on creating single endpoints for fast, ephemeral environments. The repository shows active development through recent release badges.

MCP gateway with a built-in skill library.

Command line

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

1. docs update Aug 30, 2026 · issue 011

   gridctl adds scoped variable delivery with var run, var explain, and var scan commands for secrets and env-config management.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch docs-bc4128d0269f https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout docs-bc4128d0269f

   └──▷ TRY IT
   Deliver only a specific secret to a child process — useful for running a tool with exactly the credentials it needs and nothing else.
   copy

   $ gridctl var run --only GITHUB_TOKEN -- gh auth status

   Audit where a variable is consumed across your stack before rotating or removing it.
   copy

   $ gridctl var explain GITHUB_TOKEN

   Catch missing or misconfigured variable values before they reach your repository.
   copy

   $ gridctl var scan --staged

   • ›Adds gridctl var run --only <KEY> -- <command> to select specific keys from the variable store and deliver them to a child process's environment.
   • ›Adds gridctl var explain <KEY> to inspect resolution, declaration, and consumers of a variable without exposing its value.
   • ›Adds gridctl var scan --staged to check exact variable values before commit.
   • ›Supports declaring value-free variable prerequisites in stack.yaml using ${var:KEY} references, with encrypted-at-rest storage when locked.
   • ›Reserves names beginning with GRIDCTL_, plus OP_CONNECT_TOKEN and OP_SERVICE_ACCOUNT_TOKEN, as control-plane credentials that cannot be delivered to workloads.
2. docs update Aug 30, 2026 · issue 011

   gridctl adds model routing policy management, scoped variable delivery, MCP server retry loops, and reserved credential namespacing

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch docs-8c5d14009d81 https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout docs-8c5d14009d81

   └──▷ TRY IT
   Initialize a model routing policy from an existing LiteLLM config, then render and preview changes before syncing to confirm no surprises.
   copy

   $ gridctl models init --from-litellm ~/.config/litellm/config.yaml
   gridctl models render --dry-run --diff

   Force an immediate retry of a still-pending MCP server registration via the REST API rather than waiting for the next backoff cycle.
   copy

   $ curl -X POST http://localhost:<port>/api/mcp-servers/<name>/restart

   • ›Adds gridctl models (Experimental) to manage a single model routing policy document at ~/.gridctl/models/policy.yaml, projecting it into a LiteLLM auto-router config fragment and an OpenCode provider stanza; subcommands are init (with topology templates or --from-litellm scaffolding), validate, render, --dry-run, --diff, --check, and ack-restart.
   • ›Adds /api/project/models/{status,validate,sync,adopt,ack-restart} REST endpoints backing the model routing policy, returning engine refusals as 409s with their message verbatim and running validate-before-sync so an invalid policy returns findings instead of a 500.
   • ›Adds gridctl var explain to report value-free store, environment, declaration, and consumer resolution for scoped variable delivery.
   • ›Adds gridctl var run to inject an explicit set/key selection into direct child processes with streaming exact-value redaction and signal forwarding.
   • ›Adds gridctl var scan to check working-tree or staged Git content for exact stored secret values.
   +4 moreshow less

   • ›Variables now support description, docs, example, and deprecation metadata with JSON and .env round-trip support; stack and pack manifests can declare advisory, value-free variable prerequisites.
   • ›Reserves variable names beginning with GRIDCTL_, plus OP_CONNECT_TOKEN and OP_SERVICE_ACCOUNT_TOKEN, as credential-namespace keys: new store writes reject them, imports skip them with key-only warnings, exports and variable-set injection omit legacy entries, and local MCP processes no longer inherit them from the gridctl daemon. ${var:...} and ${vault:...} references to reserved keys return a distinct resolution error without falling back to the ambient environment. Migrate legacy entries with gridctl var delete KEY --force.
   • ›Unreachable MCP servers registered at startup, via hot-reload, or via a failed restart now enter a pending-registration retry loop with exponential backoff capped at 30 s and a short reachability probe per attempt; status output shows a retrying in Ns hint, and POST /api/mcp-servers/{name}/restart forces an immediate retry instead of returning 404.
   • ›Adds a Model routing dialog in the Connections workspace (Experimental) showing per-target projection status, tier-to-backend routing summary, validation findings, and drift review with unified diffs; whole-policy actions include preview (dry-run diff), sync, adopt, forced sync, and a confirmed 'Mark restarted' that clears the restart-pending latch.
   └──▷ BREAKING ON UPGRADE

   • !Variable names beginning with GRIDCTL_, plus OP_CONNECT_TOKEN and OP_SERVICE_ACCOUNT_TOKEN, are now reserved: new store writes reject them, imports skip them, exports omit them, and local MCP processes no longer inherit them. Remove legacy entries with gridctl var delete KEY --force and move downstream credentials to non-reserved names before the next major release.
3. docs update Aug 30, 2026 · issue 011

   gridctl gains scoped variable delivery, model routing with gridctl models, LM Studio support, and GRIDCTL_HOME/gridctl reset

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch docs-d7580b750585 https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout docs-d7580b750585

   └──▷ TRY IT
   Override the gridctl home directory at runtime, then reset all gridctl state — useful in CI or multi-environment setups.
   copy

   $ GRIDCTL_HOME=/tmp/gridctl-ci gridctl reset

   Inspect current model routing policy projections to verify routing rules are applied as expected.
   copy

   $ gridctl models

   • ›Adds GRIDCTL_HOME environment variable to override the default home directory for gridctl.
   • ›Adds gridctl reset subcommand to reset gridctl state.
   • ›Adds gridctl models subcommand for model routing policy projection.
   • ›Adds a model routing surface to the web UI for visualising and managing routing policy.
   • ›Adds scoped variable delivery, enabling variables to be delivered with defined scope.
   +4 moreshow less

   • ›Adds LM Studio as a supported link client integration.
   • ›Adds pack credential collection to the import wizard in the web UI.
   • ›Adds pack import authentication parity across the engine, CLI, and REST API.
   • ›Adds a reset dialog to the web UI.
4. docs update Aug 30, 2026 · issue 011
   └──▷ GET THIS VERSION
   copy

   $ git clone --branch docs-21adeeb21bf2 https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout docs-21adeeb21bf2

   └──▷ TRY IT
   Check where a specific secret is consumed across your stack without revealing its value.
   copy

   $ gridctl var explain GITHUB_TOKEN

   Run a command with only a named variable in scope — useful for least-privilege CI steps.
   copy

   $ gridctl var run --only GITHUB_TOKEN -- gh auth status

   Catch secrets in staged changes before they reach version control.
   copy

   $ gridctl var scan --staged

   • ›Adds gridctl var run --only <KEY> -- <command> subcommand to selectively deliver scoped variables to a child process.
   • ›Adds gridctl var scan --staged subcommand to perform an exact-value check on staged files before commit.
   • ›Supports declaring value-free variable prerequisites in stack.yaml using ${var:KEY} references, with required and description fields per variable.
5. docs update Aug 30, 2026 · issue 011
   └──▷ GET THIS VERSION
   copy

   $ git clone --branch docs-0d1e8787aad9 https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout docs-0d1e8787aad9

   └──▷ TRY IT
   Inspect which workloads consume a variable without revealing its value — useful when auditing secret sprawl across a stack.
   copy

   $ gridctl var explain GITHUB_TOKEN

   Run a command with only specific secrets injected, keeping other variables out of the child process environment.
   copy

   $ gridctl var run --only GITHUB_TOKEN -- gh auth status

   Scan staged files for exact secret values before committing, to catch accidental credential leaks in CI or local pre-commit hooks.
   copy

   $ gridctl var scan --staged

   • ›Adds stack.yaml support for declaring value-free variable prerequisites, with ${var:KEY} interpolation syntax for stack references.
   • ›Variable store encrypts values at rest when locked.
6. docs update Aug 23, 2026 · issue 005
   └──▷ GET THIS VERSION
   copy

   $ git clone --branch docs-db1b2666eeba https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout docs-db1b2666eeba

   • ›Adds LM Studio as a link client integration.
7. docs update Aug 23, 2026 · issue 005

   gridctl 0.1.0-rc.3 adds LM Studio as a supported client and a post-link notes channel for client-specific guidance.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch docs-7861c320dfaf https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout docs-7861c320dfaf

   • ›Adds LM Studio as the 16th supported client, live-verified against LM Studio 0.4.x.
   • ›Introduces a post-link notes channel that surfaces client-specific guidance in the CLI and the Connections detail pane after linking.
8. v0.1.0-rc.3 Aug 22, 2026 · issue 005

   gridctl v0.1.0-rc.3 adds LM Studio as a supported link client target.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.1.0-rc.3 https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout v0.1.0-rc.3

   └──▷ TRY IT
   Link LM Studio to the running gateway with a scoped tool group to avoid overwhelming a local model with a large tool list.
   copy

   $ gridctl link lmstudio --group <name>

   • ›Adds lmstudio as a supported client for gridctl link and the link: block in stack YAML, enabling auto-configuration of LM Studio as an MCP gateway consumer (supports --group <name> to limit tool surface for local-model clients).
9. v0.1.0-rc.2 Aug 19, 2026 · issue 004

   gridctl v0.1.0-rc.2 adds GRIDCTL_HOME override, gridctl reset, OpenAPI operations picker, pack import auth, and a web UI reset dialog.

   └──▷ GET THIS VERSION
   copy

   $ git clone --branch v0.1.0-rc.2 https://github.com/gridctl/gridctl.git
   # already have the repo? check out this version:
   $ git checkout v0.1.0-rc.2

   └──▷ TRY IT
   Override the default gridctl home directory in a shared CI environment where multiple workspaces must stay isolated.
   copy

   $ GRIDCTL_HOME=/tmp/gridctl-workspace-1 gridctl apply stack.yaml

   Wipe local gridctl state when a workspace has drifted or you need a clean slate without reinstalling.
   copy

   $ gridctl reset

   • ›Adds GRIDCTL_HOME environment variable to override the default home directory, and a new gridctl reset command to clear local state.
   • ›Adds an OpenAPI operations picker to the create-server wizard, letting users select specific operations when defining an OpenAPI-backed MCP server.
   • ›Adds an OpenAPI spec preview endpoint for inspecting the resolved spec before applying.
   • ›Adds pack credential collection in the import wizard, with auth parity across the engine, CLI, and REST API.
   • ›Adds a reset dialog to the web UI.
10. v0.1.0-rc.1 Aug 10, 2026 · issue 004

    gridctl v0.1.0-rc.1 adds agents, packs, skill governance, fragment drift review, MCP dual-stack transport, and experimental feature flags in stack.yaml.

    └──▷ GET THIS VERSION
    copy

    $ git clone --branch v0.1.0-rc.1 https://github.com/gridctl/gridctl.git
    # already have the repo? check out this version:
    $ git checkout v0.1.0-rc.1

    • ›Adds agent resource kind with git import, plus REST and projection endpoints for agents (#1028, #1072).
    • ›Adds packs support for skills, agents, and wiring, with a gridctl-pack.yaml manifest, packs REST surface, and a Library Packs segment in the UI (#1044, #1079).
    • ›Adds pack provenance chips across the Library and Connections views (#1081).
    • ›Adds rules fragment library backend (#1049).
    • ›Adds fragment-level context drift review (#1077).
    +9 moreshow less

    • ›Adds 'fragments' mode in the Global Context dialog (#1050).
    • ›Adds an Agents segment to the Library workspace (#1073).
    • ›Adds skill governance backend (pins) and UI in Pins and Library (#1047, #1048).
    • ›Adds model preference support for skills and agents — backend and Library UI surfacing (#1095, #1097).
    • ›Adds MCP 2026-07-28 dual-stack transport support (#1025).
    • ›Adds per-client health hub in the Connections view (#1075).
    • ›Adds lockfile-backed wiring ownership for client links (#1033).
    • ›Adds multi-client agent renders (#1035).
    • ›Surfaces MCP protocol generation in the UI (#1026).
11. v0.1.0-beta.15 Jul 28, 2026 · issue 004

    gridctl v0.1.0-beta.15 adds MCP-native logs/traces workspaces, budget caps, tool groups, OAuth brokering, poisoning-aware pins, and declarative client linking.

    └──▷ GET THIS VERSION
    copy

    $ git clone --branch v0.1.0-beta.15 https://github.com/gridctl/gridctl.git
    # already have the repo? check out this version:
    $ git checkout v0.1.0-beta.15

    └──▷ USE IT
    Automatically link Claude Desktop and Cursor to the gateway every time you apply your stack, so you never manually edit client configs again.
    stack.yaml copy

    # stack.yaml
    version: "1"
    name: my-stack
    
    link:
      - claude
      - cursor
    
    mcp-servers:
      - name: github
        image: ghcr.io/github/github-mcp-server:latest
        transport: stdio
        env:
          GITHUB_PERSONAL_ACCESS_TOKEN: ${var:GITHUB_PERSONAL_ACCESS_TOKEN}

    Expose a focused subset of tools to local-model clients by defining a named tool group with its own /groups/release/mcp endpoint.
    stack.yaml copy

    # stack.yaml (groups section)
    groups:
      release:
        servers: [github]
        tools: [gitlab__create_merge_request]
        exclude: [github__delete_repo]

    Scan existing MCP client configs and import discovered servers into your stack, migrating secrets into the encrypted variable store.
    copy

    $ gridctl import

    • ›Adds link: block to stack.yaml for declarative client linking — lists clients (e.g. claude, cursor, grok) that are auto-linked to the gateway on every gridctl apply and removed on gridctl destroy --unlink.
    • ›Adds tool groups with per-group endpoints at /groups/{name}/mcp, configurable via a groups: block in stack.yaml with servers, tools, and exclude keys.
    • ›Adds budget caps and rate limits for MCP server usage.
    • ›Adds gridctl import to scan existing MCP client configs and append discovered servers to stack.yaml, offering plaintext secrets into the encrypted variable store.
    • ›Adds Logs and Traces workspaces to the web UI with MCP-native log list/findability and trace waterfall depth views.
    +14 moreshow less

    • ›Adds a metrics drill-down view and Overview home screen to the Metrics workspace, including limit consumption display.
    • ›Adds native OAuth brokering for remote MCP servers (authorize once with gridctl auth login <provider>; tokens stored encrypted and auto-refreshed).
    • ›Adds poisoning-aware pins with injection heuristics evaluated at pin and approve time.
    • ›Adds pins review with word and schema diffs, plus review actions and findings ergonomics.
    • ›Adds a server catalog with search and gridctl add command for appending catalog servers to stack.yaml by name.
    • ›Adds a catalog picker to the add-server wizard in the web UI.
    • ›Adds a tool groups panel to the web UI.
    • ›Adds Variables least-privilege scoping and trust controls.
    • ›Adds Tools workspace audit filters, annotations, and tool-level access controls.
    • ›Adds a Library workspace for managing skills.
    • ›Adds wizard-based auth configuration for external MCP servers with OAuth/bearer/header options.
    • ›Surfaces server authorization controls in the web UI.
    • ›Projects skills into native client skill directories.
    • ›Adds a resizable Traces workspace layout.