One endpoint. Dozens of AI tools. Zero configuration drift.

Gridctl aggregates tools from multiple MCP servers into a single gateway. Connect Claude Desktop - or any MCP client - to your grid through one endpoint and start building.

Define your stack in YAML. Deploy with one command. Done.

gridctl deploy stack.yaml

MCP servers are everywhere. Running them shouldn't require a PhD in container orchestration. Or, is the MCP server not running in a container? Is a single endpoint exposed behind an existing platform? Is another team hosting and managing an MCP server that is on a different machine on the same network? Different transport types, methods of hosting, and .json files start to accumulate like dust.

I originally built this project to have a way to leverage a single configuration in my application, that I never have to update, while still building various combinations of MCP servers and Agents for rapid prototyping and learning.

I would rather be building than juggling ports, tracking environment variables, and hoping everything with my setup is ready for the next demo, no matter what servers or agents I'm using. My client now connects once and accesses everything over localhost:8180/sse by default.

version: "1"
name: stack

mcp-servers:

  # Build GitHub MCP locally (instantiate in Docker container)
  - name: github
    image: ghcr.io/github/github-mcp-server:latest
    transport: stdio
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"

  # Connects to external SaaS/Cloud Atlassian Rovo MCP Server (breaks out into OAuth to connect)
  - name: atlassian
    command: ["npx", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]

agents:

  # Test Agent - A2A
  - name: code-reviewer
    image: alpine:latest
    description: "AI assistant for code review and PR analysis"
    command: ["sh", "-c", "while true; do sleep 3600; done"]

    # Agent Level Filtering for Tools
    uses:
      - server: github
        tools: ["get_file_contents", "get_pull_request", "list_commits"]

    # Agent Definition
    a2a:
      enabled: true
      version: "1.0.0"
      skills:
        - id: review-code
          name: "Review Code"
          description: "Analyze code changes for bugs, style issues, and improvements"
          tags: ["code", "review", "quality"]
        - id: summarize-pr
          name: "Summarize PR"
          description: "Generate concise summaries of pull request changes"
          tags: ["summary", "documentation"]

Three servers. Three different transports. One endpoint. Navigate to localhost:8180 to visualize the stack 👉

# macOS / Linux
brew install gridctl/tap/gridctl

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

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

Gridctl requires a container runtime for workloads that run in containers (MCP servers with image, resources, agents). Docker is detected by default; Podman is supported as an experimental alternative.

Gridctl auto-detects your runtime by probing sockets in this order:

1. $DOCKER_HOST (if set)
2. /var/run/docker.sock (Docker)
3. /run/podman/podman.sock (Podman rootful)
4. $XDG_RUNTIME_DIR/podman/podman.sock (Podman rootless)

Override detection with the --runtime flag or GRIDCTL_RUNTIME environment variable:

gridctl deploy stack.yaml --runtime podman
# or
GRIDCTL_RUNTIME=podman gridctl deploy stack.yaml

# Install Podman (macOS)
brew install podman
podman machine init
podman machine start

# Install Podman (Linux)
sudo apt install podman        # Debian/Ubuntu
sudo dnf install podman        # Fedora/RHEL

# Enable the Podman socket (Linux rootless)
systemctl --user enable --now podman.socket

# Verify gridctl detects Podman
gridctl info

Podman 4.7+ is recommended for full host.containers.internal support. Older versions fall back to the Docker-compatible host.docker.internal alias. SELinux volume labels (:Z) are applied automatically when Podman is running on an SELinux-enforcing system.

# Deploy the example stack
gridctl deploy examples/getting-started/skills-basic.yaml

# Check what's running
gridctl status

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

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

Fast, consistent, ephemeral, flexible, and version controlled! Many practitioners use different combinations of MCP Servers and Agents depending on what they are working on. Being able to instantiate, from a single file, the various combinations needed for the right task, saves time in development and prototyping. The stack.yaml file is where you define this.

The stack.yaml file has always been your source of truth. Now you have the full lifecycle tooling to match — validate before you commit, preview before you deploy, and detect the moment your environment drifts from what's in version control:

gridctl validate stack.yaml    # Lint and schema-check the spec (exit 0/1/2)
gridctl plan stack.yaml        # Diff against running state — see exactly what changes
gridctl deploy stack.yaml      # Apply the spec
gridctl export                 # Reverse-engineer stack.yaml from a running stack

Drift detection runs in the background: the canvas flags servers that are running but absent from your spec, and declarations in your spec that haven't been deployed — so your YAML and your environment stay in sync. Need to build a stack from scratch? The visual spec builder lets you compose stack.yaml through a guided wizard and export the result.

Aggregates tools from HTTP servers, stdio processes, SSH tunnels, and external URLs into a unified gateway. Automatic namespacing (server__tool) prevents collisions.

Are you paying for your own tokens for learning? Even if you aren't, being optimized is critical for not overloading that context window! Reducing the numbers of tools and scoping things out correctly, significantly reduces the likelihood of "tool confusion" e.g., a given LLM selects a similarly named tool from the wrong server.

By using uses and tools filters in the stack.yaml file, gridctl filters this list before it reaches the LLM. This way, you only get what you need. Filtering is enforced at two levels:

• Server-level: tools are whitelisted when gridctl connects to the downstream MCP server — unauthorized tools are never loaded into the gateway
• Agent-level: the gateway validates every tool list request and tool call against the requesting agent's ToolSelector — unauthorized calls are rejected even if the model knows the tool name

Server-Level Filtering - Restrict which tools the server exposes to the gateway:

mcp-servers:
  - name: github
    image: ghcr.io/github/github-mcp-server:latest
    transport: stdio
    tools: ["get_file_contents", "search_code", "list_commits", "get_issue", "get_pull_request"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"

This GitHub server only exposes read-only tools. Write operations like create_issue and create_pull_request are hidden from all agents.

Agent-Level Filtering - Further restrict which tools a specific agent can access:

agents:
  - name: code-review-agent
    image: my-org/code-review:latest
    description: "Reviews pull requests and provides feedback"
    uses:
      - server: github
        tools: ["get_file_contents", "get_pull_request", "list_commits"]

This agent can only access three of the five tools exposed by the GitHub server - just enough to review code without searching the broader codebase.

Limited Agent-to-Agent protocol support. Expose your agents via /.well-known/agent.json or connect to remote A2A agents. Agents can use other agents as tools. A2A is still emerging, as is the common use-cases. This part of the project will continue to evolve in the future.

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.

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

mcp-servers:
  - name: analytics
    image: my-org/analytics:latest
    port: 8080
    output_format: csv      # Override: this server returns CSV

Non-JSON responses and payloads over 1MB are passed through unchanged. Per-server settings override the gateway default.

When a stack exposes dozens of tools, context window consumption grows fast. Code Mode replaces all individual tool definitions with two meta-tools — search and execute — reducing context overhead by 99%+. LLM agents discover tools via search, then call them through JavaScript executed in a sandboxed goja runtime.

gateway:
  code_mode: "on"
  code_mode_timeout: 30     # Execution timeout in seconds (default: 30)

Or enable via CLI flag:

gridctl deploy stack.yaml --code-mode

The sandbox provides mcp.callTool(serverName, toolName, args) for synchronous tool calls and console.log/warn/error for output capture. Modern JavaScript syntax (arrow functions, destructuring, template literals) is supported via esbuild transpilation. Agent-level ACLs are enforced inside the sandbox — agents can only call tools they have access to. See examples/code-mode/ for a working example.

Store reusable skills as SKILL.md files — markdown documents with YAML frontmatter that get exposed to LLM clients as MCP prompts. Create them via the REST API, Web UI, or by dropping files into ~/.gridctl/registry/skills/.

~/.gridctl/registry/skills/
└── code-review/
    ├── SKILL.md              # Frontmatter + markdown instructions
    └── references/           # Optional supporting files

Skills have three lifecycle states: draft (stored, not exposed), active (discoverable via MCP), and disabled (hidden without deletion). See examples/registry/ for working examples.

Add inputs, workflow, and output blocks to a SKILL.md frontmatter to make it executable. Executable skills are exposed as MCP tools and run deterministic multi-step tool orchestration through the gateway.

inputs:
  a: { type: number, required: true }
  b: { type: number, required: true }

workflow:
  - id: add
    tool: math__add
    args: { a: "{{ inputs.a }}", b: "{{ inputs.b }}" }
  - id: echo
    tool: text__echo
    args: { message: "{{ steps.add.result }}" }
    depends_on: add

output:
  format: last

Steps without dependencies run in parallel. Template expressions reference inputs ({{ inputs.x }}) and prior step results ({{ steps.id.result }}). Each step supports retry policies, timeouts, conditional execution, and configurable error handling (fail / skip / continue). The Web UI includes a visual workflow designer with Code, Visual, and Test modes. See examples/registry/ for working examples.

Every tool call through the gateway is captured as an OpenTelemetry trace. Spans record transport type, server name, duration, and error state. The last 1000 traces are kept in a ring buffer and are queryable via CLI or the Web UI.

# List recent traces
gridctl traces

# Inspect a single trace as a span waterfall
gridctl traces <trace-id>

# Stream traces in real time
gridctl traces --follow

The Web UI includes a Traces tab in the bottom panel with an interactive waterfall view, span detail panel, and a pop-out window. Canvas edges light up with latency heat based on recent trace data.

gridctl validate <stack.yaml>        # Validate stack YAML before deploying (exit 0/1/2)
gridctl plan <stack.yaml>            # Preview changes against running state
gridctl deploy <stack.yaml>          # Start containers and gateway
gridctl deploy <stack.yaml> -f       # Run in foreground (debug mode)
gridctl deploy <stack.yaml> -p 9000  # Custom gateway port
gridctl deploy <stack.yaml> --watch  # Watch for changes and hot reload
gridctl deploy <stack.yaml> --flash  # Deploy and auto-link LLM clients
gridctl deploy <stack.yaml> --code-mode  # Enable code mode (search + execute)
gridctl deploy <stack.yaml> --no-cache   # Force rebuild of source-based images
gridctl deploy <stack.yaml> -v       # Print full stack as JSON
gridctl deploy <stack.yaml> -q       # Suppress progress output
gridctl deploy <stack.yaml> --log-file <path>  # Structured JSON log output with rotation
gridctl export                       # Reverse-engineer stack.yaml from running stack
gridctl serve                        # Start the web UI without managing a stack
gridctl status                       # Show running stacks
gridctl info                         # Show detected container runtime
gridctl link                         # Connect an LLM client to the gateway
gridctl unlink                       # Remove gridctl from an LLM client
gridctl reload                       # Hot reload a running stack
gridctl destroy <stack.yaml>         # Stop and remove containers
gridctl vault set <key> <value>      # Store a secret in the encrypted vault
gridctl vault get <key>              # Retrieve a secret from the vault
gridctl vault list                   # List all vault keys
gridctl vault lock / unlock          # Lock or unlock the vault
gridctl skill list                   # List skills in the registry
gridctl skill add <repo-url>         # Import skills from a remote git repository
gridctl skill update [name]          # Update imported skills (all if no name given)
gridctl skill remove <name>          # Remove an imported skill
gridctl skill pin <name> <ref>       # Pin a skill to a specific git ref
gridctl skill info <name>            # Show skill origin and update status
gridctl skill try <repo-url>         # Temporarily import a skill for evaluation
gridctl traces                       # Show recent distributed traces (table view)
gridctl traces <trace-id>            # Show span waterfall for a single trace
gridctl traces --follow              # Stream new traces as they arrive
gridctl traces --server <name>       # Filter by MCP server name
gridctl traces --errors              # Show only error traces
gridctl traces --min-duration 100ms  # Filter by minimum duration
gridctl traces --json                # Output as JSON

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

Supported clients: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Gemini, OpenCode, Continue, Cline, AnythingLLM, Roo, Zed, Goose

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

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

• Podman rootless networking requires slirp4netns or pasta for inter-container communication
• A2A protocol support is experimental and tracks the evolving spec
• Code mode sandbox has no filesystem access (by design)
• Skills registry is local-only with no remote discovery
• Web UI requires a modern browser (no IE11 support)

• Configuration Reference — every field in stack.yaml
• REST API Reference — all gateway endpoints
• Troubleshooting — common issues and resolutions

See CONTRIBUTING.md. We welcome PRs for new transport types, example stacks, and documentation improvements.

Apache 2.0

_{Built for engineers who'd rather be building and hate the absence of repeatable environments!}