gridctl

Gridctl is an MCP gateway with a built-in skill library, whose goal is to let developers put their agent configurations under version control. MCP servers, skills, agent definitions, and rules are all declared as committable files. Gridctl runs MCP servers behind one gateway; separately, a distinct projection mechanism writes skills, agent definitions, and rules into supported clients.

Purpose and Positioning

Gridctl is aimed at developers maintaining their own agent environments or team-shared environments. It makes MCP servers, skills, agent definitions, and rules belong to files, while running processes, secret values, and client installations on each machine do not belong to files. The committed stack file is what gridctl apply starts on that host, but the result depends on the pinned versions in the file and the host capable of running them; it does not promise fully consistent agent behavior. Gridctl does not run an agent's planning or model loop and needs to be paired with an agent runtime of your choice; gridctl plan is a separate command used to preview deployment changes, not to plan agent work.

Main Capabilities

1. Declarative, version-controllable MCP environments: define MCP server stacks in YAML, start them and expose them through one gateway; validate before committing, preview before applying, and detect environment drift. Drift detection runs in the background, flagging servers that are running but not in the spec, as well as content that is declared but not yet deployed.
2. Skill library and registry: each SKILL.md in the registry is exposed upstream to MCP clients as a prompt, and can enter the registry via a git repository, local directory, client import, or pack. Skills follow the agentskills.io specification and are plain Markdown with frontmatter.
3. Client connections: gridctl link automatically detects installed LLM clients and injects the gateway configuration, without installing skills, agents, or rules; declaring a link block in stack.yaml enables idempotent connection of the listed clients on each apply. Supported clients include Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini, Antigravity, OpenCode, Grok Build, Continue, Cline, AnythingLLM, LM Studio, Roo, Zed, Goose.
4. Import: gridctl import reverse-scans client configurations, deduplicates servers and appends them to stack.yaml, and can write plaintext secrets into encrypted variable storage; gridctl import <client> --kind all imports that client's skills, agents, and global context in a single run.
5. Runtime control: provides MCP execution control (hardened and local modes), tool call rate limiting, and call rate limits by client/server/tool.
6. Tool surface control: through per-server tools: allowlists, groups: cross-server grouped endpoints (/groups/{name}/mcp), and clients: to restrict what each client can access.
7. Output format conversion: tool call results are JSON by default, and output_format can be set at the gateway or per-server level to convert to TOON or CSV, reducing token consumption by 25-61% for tabular and key-value data; non-JSON responses and payloads over 1 MB are passed through as-is, and format conversion only rewrites text blocks.
8. Usage observability and optimization: records the parameters and results of each successful tool dispatch; the Metrics workspace shows throughput, call counts, and format-conversion savings; gridctl optimize scans a running gateway, gives actionable findings and estimated weekly token impact, along with paste-ready YAML fixes.
9. Supply chain trust: tool definitions are pinned the first time they are seen, and later apply runs flag drift; pinned definitions are scanned for injection signals such as hidden instructions, sensitive file references, hidden Unicode, and cross-server tool shadowing; skill documents likewise use trust on first use, with per-file digests and drift requiring manual approval.
10. Downstream authorization: for OAuth-protected remote servers, gridctl acts as an OAuth client, with a single browser login serving all connected clients, and tokens stored encrypted and refreshed automatically.
11. Scoped variable delivery: secrets and environment configuration are stored in variable storage (statically encrypted once locked), stack.yaml declares value-less preconditions, and you can inspect where each key is consumed without exposing the value; keys beginning with GRIDCTL_ and OP_CONNECT_TOKEN and OP_SERVICE_ACCOUNT_TOKEN are reserved for the control plane and cannot be delivered to workloads.
12. Live tool calls: without starting a daemonyou can search for and call tools on a selected running gateway.
13. Outbound A2A (experimental): declare a remote Agent Card under a2a: and enable experimental.a2a to expose A2A 1.0/0.3 JSON-RPC send, task-get, task-cancel, and advisory skill tools to MCP clients; disabled by default.
14. Generative Python containers: build exact public PyPI releases or packaged Python projects from git or local directories without maintaining a Dockerfile; generated images use pinned Python and uv bases and run as a non-root user.

Usage

The installer installs the latest release to ~/.local/bin/gridctl; see the installation guide for Homebrew, prebuilt binaries, source builds, container runtime setup, and more. The installer verifies SHA256 rather than the release source, so it is recommended to verify according to Release Verification before extracting or installing. Docker or Podman is required, and the first build needs network access to PyPI. gridctl init generates a starter stack.yaml, but that scaffold is not a verified tool server. gridctl link detects clients and lets the user choose; explicit commands such as gridctl link claude-code exit with 1 when the client is not installed. By default apply listens on port 8180, and the Web UI is at http://localhost:8180，仅用于查看，不是调用路径。网关认证与监听安全设置为仅重启生效，reload will reject secure changes.

Limitations

Gridctl is not responsible for the agent's planning or model loop; container observation requires a supported Linux daemon environment; the A2A adapter is disabled by default and experimental, and task and context handles are bearer secrets that expire after 24 hours and become invalid when the adapter is replaced or restarted; in the tool surface control, groups and self-declared client selectors are not authenticated identities; exported stack files may still contain credentials, and you must review them yourself before sharing.