feat: add MCP server command exposing the CLI to AI agents

[wuyuwenj]

Summary

Adds superplane mcp, a new CLI subcommand that runs a Model Context Protocol server over stdio, auto-exposing the entire SuperPlane CLI as MCP tools. This lets AI coding agents (Claude Code, Codex, etc.) operate SuperPlane directly
— listing canvases, creating workflows, inspecting executions, managing secrets — without the developer memorizing CLI flags or leaving their editor.

How it works

• Auto-generated tools: At startup, superplane mcp walks the Cobra command tree and registers one MCP tool per runnable leaf command (~71 tools). Tool names are derived from the command path (canvases_list, secrets_create, executions_list, …) and input
  schemas are derived from each command's flags (string → string, bool → boolean, StringArray → array[string], positional args → args: array[string]).
• Shell-out execution: Each tool call invokes os.Executable() with the mapped command path, flags, and --output json, capturing stdout as structured JSON. Non-zero exits return an MCP tool error with stderr. This reuses the CLI's existing auth context
  (~/.superplane.yaml) with zero additional configuration.
• Fault-isolated registration: Commands with unmappable flag types are skipped (not crashed) — one bad command never breaks the whole server.
• --read-only flag: Exposes only read commands (list, get, describe, show, …) for safe, restricted usage.

Installation (one command)

claude mcp add superplane -- superplane mcp

Then /mcp in Claude Code lists all SuperPlane tools immediately. Works with any MCP-compatible agent.

Also included

- Canvas url field in JSON output: canvases create now includes a canonical url field in JSON/YAML output, so agents receive a clickable link instead of constructing one (which they get wrong — the web app route is /{orgId}/canvases/{id}, not /organizations/…).
- Demo canvas: mcp-demo/canvas.yaml — a tested, integration-free deploy-gate workflow (webhook → time gate → approval → HTTP deploy) that works out of the box on any local instance.

Files changed

┌────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────────────────┐
│                    File                    │                                     What                                      │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ pkg/cli/commands/mcp/root.go               │ NewCommand() — the superplane mcp subcommand with --read-only flag            │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ pkg/cli/commands/mcp/server.go             │ stdio MCP server setup using modelcontextprotocol/go-sdk v1.6.1               │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ pkg/cli/commands/mcp/tools.go              │ Cobra tree walker → MCP tool generator (flag→schema mapping, fault isolation) │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ pkg/cli/commands/mcp/execute.go            │ Shell-out executor (os.Executable() + -o json, exit-code → result/error)      │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ pkg/cli/root.go                            │ One-line wiring: RootCmd.AddCommand(mcpcmd.NewCommand(options))               │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ pkg/cli/commands/canvases/create.go        │ Populate url field on canvas create JSON output                               │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ pkg/cli/commands/canvases/models/canvas.go │ Add url field to Canvas resource (json:"url,omitempty", hidden from YAML)     │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ mcp-demo/canvas.yaml                       │ Integration-free demo canvas for testing/onboarding                           │
├────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────────────────┤
│ go.mod / go.sum                            │ Add modelcontextprotocol/go-sdk v1.6.1 + google/jsonschema-go v0.4.3          │
└────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────────────────┘

Demo

Split screen — Claude Code on the left, SuperPlane Canvas on the right:

> set up a health monitor: check trustgate every minute, ping #deploy if it's down
→ agent writes canvas YAML, calls canvases_create, canvas appears live

> is trustgate healthy?
→ agent reads executions: "health check failing since 22:53, alerted #deploy"

> why is it down?
→ agent reads SuperPlane state + git history + source code
→ "commit 09d9cd3 changed /health to return 500 — line 9 of src/index.ts"

> fix it and push
→ agent edits the code, commits, pushes — monitor confirms recovery on next run

The key differentiator: the agent joins SuperPlane's operational state with the developer's codebase to find root cause — something neither the web UI nor a single-vendor MCP can do.

https://github.com/user-attachments/assets/placeholder-for-demo-video

Test plan

- [ ] go build ./cmd/cli compiles clean
- [ ] superplane mcp --help prints usage
- [ ] superplane mcp starts a stdio server; tools/list returns ~71 tools with correct schemas
- [ ] tools/call canvases_list returns real JSON from a connected instance
- [ ] tools/call canvases_create with a name arg creates a canvas and returns a url field
- [ ] --read-only hides mutating tools (create/delete/update)
- [ ] claude mcp add superplane -- superplane mcp registers successfully; /mcp shows tools
- [ ] Commands with exotic flag types are skipped, not crashed

[superplanehq-integration]

👋 Commands for maintainers:

• /sp start - Start an ephemeral machine (takes ~30s)
• /sp stop - Stop a running machine (auto-executed on pr close)