# Gridctl

> 🧪 Local dev stack for MCP and Agent Skills

- **Type:** MCP server
- **Install:** `agentstack add mcp-gridctl-gridctl`
- **Verified:** Pending review
- **Seller:** [gridctl](https://agentstack.voostack.com/s/gridctl)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [gridctl](https://github.com/gridctl)
- **Source:** https://github.com/gridctl/gridctl

## Install

```sh
agentstack add mcp-gridctl-gridctl
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

MCP gateway with a built-in skill library.

  One YAML. One endpoint. Every MCP server plus the skills you author alongside them.

  
  
  
  
  
  

---

Gridctl aggregates tools from [MCP](https://modelcontextprotocol.io/) servers into a single gateway and serves [Agent Skills](https://agentskills.io) 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.

```bash
gridctl apply stack.yaml
```

Designed for fast, ephemeral, stateless environments, inspired by [Containerlab](https://containerlab.dev).

## ⚡️ 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.

```yaml
version: "1"
name: stack

mcp-servers:

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

  # External SaaS MCP server (OAuth flow)
  - name: atlassian
    command: ["npx", "mcp-remote", "https://mcp.atlassian.com/v1/sse"]

  # Any REST API as MCP tools via OpenAPI
  - name: my-api
    openapi:
      spec: https://api.example.com/openapi.json
      baseUrl: https://api.example.com
```

Three servers, three transports, one endpoint. Navigate to [localhost:8180](http://localhost:8180) to visualize the stack 👉

## 🪛 Install

```bash
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](docs/installation.md).

## 🚦 Quick Start

```bash
# Apply the example stack
gridctl apply 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
```

## 🖥️ Connect LLM Application

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

```bash
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, Antigravity, OpenCode, Grok Build, Continue, Cline, AnythingLLM, Roo, Zed, Goose

Manual configuration

#### Most Applications
```json
{
  "mcpServers": {
    "gridctl": {
      "url": "http://localhost:8180/sse"
    }
  }
}
```

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

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

#### Antigravity
```json
{
  "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`.

## 🎬 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.

```bash
gridctl validate stack.yaml    # Lint and schema-check the spec (exit 0/1/2)
gridctl plan stack.yaml        # Diff against running state
gridctl apply stack.yaml       # Apply the spec
gridctl export                 # Reverse-engineer stack.yaml from a running stack
```

Learn more → [Configuration Reference](docs/config-schema.md)

### `gridctl optimize` & Cost Observability

Every tool call is priced against an embedded snapshot of LiteLLM model rates. `gridctl optimize` scans the running gateway and surfaces actionable findings with weekly USD impact (unused servers, unused tools, schema overhead, format-conversion shortfalls, and expensive-model-on-cheap-task patterns), plus a paste-ready YAML remediation for each.

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

Learn more → [Cost Observability](docs/cost-observability.md)

### 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.

```yaml
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](docs/config-schema.md)

### Skill Library

Every `SKILL.md` in your registry surfaces to upstream MCP clients as a prompt. Author in the Library workspace in the web UI (or via `gridctl skill *` on the CLI), activate, and the prompt becomes available to Claude Desktop, Claude Code, Cursor, Codex, or anything that speaks MCP.

```bash
gridctl skill list                        # Show what's in the registry
gridctl skill add               # Import skills from a remote repo
gridctl activate my-skill                 # Promote a draft → active
```

Skills follow the [agentskills.io specification](https://agentskills.io): author them as plain markdown with frontmatter and they work with every skill-aware client, not just gridctl.

Learn more → [Skills guide](docs/skills.md)

## 📙 Examples

| Example | What It Shows |
|:--------|:--------------|
| [`mcp-basic.yaml`](examples/getting-started/mcp-basic.yaml) | Stack with multiple MCP servers and tool filtering |
| [`local-mcp.yaml`](examples/transports/local-mcp.yaml) | Local process and SSH-tunneled MCP transports |
| [`openapi-basic.yaml`](examples/openapi/openapi-basic.yaml) | Turn a REST API into MCP tools via OpenAPI spec |
| [`code-mode-basic.yaml`](examples/code-mode/code-mode-basic.yaml) | Gateway code mode with search + execute meta-tools |
| [`github-mcp.yaml`](examples/platforms/github-mcp.yaml) | GitHub MCP server integration |
| [`registry-basic.yaml`](examples/registry/registry-basic.yaml) | Skills registry with a single server |
| [`var-basic.yaml`](examples/secrets-vault/var-basic.yaml) | Reference variable-store secrets with `${var:KEY}` syntax |
| [`otlp-jaeger.yaml`](examples/tracing/otlp-jaeger.yaml) | Export traces to Jaeger via OTLP |

## 📖 Documentation

- **Getting started**: [Installation](docs/installation.md)
- **Reference**: [CLI](docs/cli-reference.md) · [Configuration](docs/config-schema.md) · [REST API](docs/api-reference.md)
- **Guides**: [Skills](docs/skills.md) · [Scaling](docs/scaling.md) · [Cost Observability](docs/cost-observability.md)
- **Operations**: [Project Status](docs/project-status.md) · [Troubleshooting](docs/troubleshooting.md)

Full index at [`docs/`](docs/README.md).

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome for new transport types, example stacks, and documentation improvements.

## 🪪 License

[Apache 2.0](LICENSE)

---

  Built for engineers who'd rather be building and hate the absence of repeatable environments.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gridctl](https://github.com/gridctl)
- **Source:** [gridctl/gridctl](https://github.com/gridctl/gridctl)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gridctl-gridctl
- Seller: https://agentstack.voostack.com/s/gridctl
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.