gridctl

Gridctl acts as a single gateway that aggregates tools from multiple MCP servers into one endpoint. It enables you to connect an MCP client (like Claude Desktop or any MCP-compatible client) to a unified stack exposed at a single URL (default localhost:8180). The interface and YAML-driven stack let you define multiple servers and agents, control which tools are exposed to which agents, and deploy ephemeral, repeatable environments. Tools from each downstream MCP server are namespaced (server__tool) to prevent collisions, and Gridctl supports various transports (container HTTP, container stdio, local processes, SSH tunnels, external URLs, or OpenAPI specs) so you can mix and match hosting methods without changing client code. You can start with the example stack and then customize the mcp-servers and agents sections to fit your needs.

To use Gridctl’s capabilities, deploy a stack YAML that declares your MCP servers and agents, then use the provided commands to view status, access the web UI, and destroy the stack when finished. The gateway automatically filters tools at both the server and agent levels, ensuring that clients only see and can invoke permitted tools. This makes it suitable for rapid prototyping, demonstrations, and teaching scenarios where you want a single endpoint to manage diverse tooling across multiple environments.

Prerequisites:

• A recent operating system (macOS or Linux) with a working shell
• Git and a Go-compatible toolchain if building from source (optional)
• Internet access to fetch binaries or dependencies

Installation steps (recommended):

1. Install via Homebrew (macOS / Linux):

brew install gridctl/tap/gridctl

2. Verify installation:

gridctl version

3. If you prefer building from source or using binary releases:

# From source
git clone https://github.com/gridctl/gridctl
cd gridctl && make build

# Binary releases available at:
# https://github.com/gridctl/gridctl/releases

4. Start Gridctl (example):

# Ensure you have a suitable stack.yaml or configure a default one
gridctl deploy examples/getting-started/skills-basic.yaml

5. Access the web UI at http://localhost:8180 and manage your stack from there.

Tips and known considerations:

• Gridctl exposes tools via a single gateway; use the server and agent filtering features to minimize tool surface area for each agent.
• Tools are namespaced as server__tool, which helps prevent collisions when aggregating across multiple MCP servers.
• If you run into port or UI issues, ensure the GRIDCTL_PORT (default 8180) is open and not blocked by a firewall.
• When using container transports, you can manage servers as Docker containers or OpenAPI-enabled endpoints; combine transports to fit your environment.
• For reproducible demos, keep your stack YAML under version control and leverage the stack as code approach described in the docs.
• If you modify environment variables for servers (env), make sure to refresh tools so the gateway can cache the updated configuration.