Skip to content

canopyide/canopy-orchestrator

BranchesTags

Repository files navigation

Canopy MCP Consumer

An agent-agnostic orchestration layer for Canopy IDE. Launch any supported AI coding agent in this directory and it will automatically connect to Canopy's MCP server, giving it full control over the IDE — launching agents, managing terminals, coordinating multi-agent workflows, and more.

What is This?

Canopy is a desktop IDE built for orchestrating multiple AI coding agents in parallel. It manages Claude, Gemini, Codex, and OpenCode sessions across git worktrees with integrated terminals, a built-in browser (sidecar), project notes, and workflow automation.

Canopy exposes its entire action system as an MCP (Model Context Protocol) server. This project is a pre-configured workspace that any MCP-compatible AI coding agent can drop into and immediately start controlling Canopy. Each agent gets:

  1. MCP server configuration — so it can discover and call Canopy's ~250 tools
  2. Instruction files — so it understands Canopy's concepts, available tools, key workflows, and safety rules

The result: you cd into this directory, launch your agent of choice, and tell it what to do in Canopy.

How It Works

┌─────────────────────┐         MCP (SSE)         ┌──────────────────┐
│   AI Coding Agent   │◄────────────────────────►  │   Canopy IDE     │
│                     │    localhost:45454/sse      │                  │
│  Claude / Gemini /  │                            │  Terminals       │
│  Codex / OpenCode / │   ┌──────────────────┐     │  Agents          │
│  Goose / Kiro /     │   │  This Project    │     │  Worktrees       │
│  Amazon Q / Cline / │   │                  │     │  Sidecar Browser │
│  Amp                │   │  MCP configs +   │     │  Git / GitHub    │
│                     │   │  Agent-specific  │     │  Notes           │
│  Reads instruction  │   │  instructions    │     │  Events          │
│  files from here    │   └──────────────────┘     │                  │
└─────────────────────┘                            └──────────────────┘

The MCP connection gives agents access to tools across these categories:

Category What Agents Can Do
Agent Orchestration Launch Claude, Gemini, Codex, or OpenCode sessions inside Canopy. Send prompts, read responses, send follow-ups.
Terminal Management Create terminals, execute shell commands, read output, move panels between grid and dock.
Multi-Agent Coordination Run multiple agents in parallel, read each agent's output, cross-pollinate findings between them.
Sidecar Browser Open URLs inline, manage tabs, navigate history.
Git Integration List commits, check staging status, view diffs, get project activity heatmaps.
GitHub Integration List issues and pull requests with pagination, view linked PRs/issues per worktree.
Worktree Management List all git worktrees, inspect branches, check active worktree and its linked issue/PR.
Project State Get current project info, resource usage stats, terminal counts, process counts.
Notes Create, list, and read persistent markdown notes scoped to project or worktree.
Event Inspection Subscribe to IDE events and filter by category (agent, system, task, file, UI).
Context Generation Generate AI-optimized codebase context via CopyTree.
Introspection List all available actions, get current UI context (focused terminal, active worktree, sidecar state).

Supported Agents

Project-Level Configuration (Zero Setup)

These agents auto-discover the MCP server from config files in this directory. Just cd in and run them.

Agent Instruction File MCP Config Links
Claude Code CLAUDE.md .mcp.json Docs
Gemini CLI GEMINI.md .gemini/settings.json Docs
Codex CLI AGENTS.md .codex/config.toml Docs
OpenCode AGENTS.md opencode.json Docs
Kiro .kiro/steering/*.md .kiro/settings/mcp.json Docs
Amazon Q Developer .amazonq/rules/AGENTS.md .amazonq/mcp.json Docs

Global Configuration Required

These agents don't support project-level MCP config. You need a one-time setup in their global settings, but they will still read project-level instruction files automatically.

Agent Instruction File Global Config Location Links
Goose AGENTS.md + .goosehints ~/.config/goose/config.yaml Docs
Cline .clinerules ~/.cline/data/settings/cline_mcp_settings.json Docs
Amp AGENTS.md ~/.config/amp/settings.json Docs

Prerequisites

  1. Canopy must be running with the MCP server enabled
    • Open Canopy > Settings > MCP Server > Enable
    • Default endpoint: http://127.0.0.1:45454/sse
  2. At least one agent CLI must be installed (e.g., claude, gemini, codex)

Quick Start

# Clone this repo
git clone https://github.com/canopyide/canopy-mcp-consumer.git
cd canopy-mcp-consumer

# Launch any agent — it connects to Canopy automatically
claude    # or gemini, codex, opencode, goose, kiro, q chat, cline, amp

Then tell the agent what to do:

"Launch a Claude agent in Canopy to refactor the authentication module, and launch a Gemini agent to write tests for it. Read both outputs and create a summary note."

The agent will use Canopy's MCP tools to execute each step.

Example Workflows

Launch an Agent and Read Its Response

You: "Launch Claude in Canopy and ask it to explain the auth module"

Agent calls:
  1. agent_launch(agentId: "claude", prompt: "Explain the auth module", location: "grid")
     → { terminalId: "abc-123" }
  2. terminal_getOutput(terminalId: "abc-123", maxLines: 50)
     → Claude's response text
  3. terminal_sendCommand(terminalId: "abc-123", command: "Now suggest improvements")
     → Follow-up sent

Multi-Agent Coordination

You: "Have Claude review the PR and Gemini write tests, then combine findings"

Agent calls:
  1. agent_launch(agentId: "claude", prompt: "Review PR #42", location: "grid")  → idA
  2. agent_launch(agentId: "gemini", prompt: "Write tests for auth", location: "dock")  → idB
  3. terminal_getOutput(idA)  → Claude's review
  4. terminal_getOutput(idB)  → Gemini's tests
  5. notes_create(title: "PR #42 Summary", content: "...")  → combined findings

Project Inspection

You: "What's the current state of the project?"

Agent calls:
  1. actions_getContext()       → focused terminal, active worktree
  2. worktree_list()           → all worktrees with branches and PR links
  3. git_listCommits(cwd, 5)   → last 5 commits
  4. github_listIssues(cwd)    → open issues
  5. project_getStats()        → terminal count, memory usage

Global MCP Setup

For agents that require global configuration, add the Canopy MCP server to their settings:

Goose

Add to ~/.config/goose/config.yaml:

extensions:
  canopy:
    enabled: true
    name: canopy
    type: sse
    url: "http://127.0.0.1:45454/sse"

Cline CLI

Add to ~/.cline/data/settings/cline_mcp_settings.json:

{
  "mcpServers": {
    "canopy": {
      "url": "http://127.0.0.1:45454/sse",
      "type": "sse",
      "disabled": false
    }
  }
}

Amp

Add to ~/.config/amp/settings.json:

{
  "amp.mcpServers": {
    "canopy": {
      "url": "http://127.0.0.1:45454/sse"
    }
  }
}

API Key Authentication

If Canopy's MCP server is configured to require an API key (recommended for shared environments), update each agent's config:

Claude Code (.mcp.json):

{
  "mcpServers": {
    "canopy": {
      "type": "sse",
      "url": "http://127.0.0.1:45454/sse",
      "headers": { "Authorization": "Bearer canopy_<your-key>" }
    }
  }
}

Gemini CLI (.gemini/settings.json):

{
  "mcpServers": {
    "canopy": {
      "url": "http://127.0.0.1:45454/sse",
      "headers": { "Authorization": "Bearer canopy_<your-key>" }
    }
  }
}

Codex CLI (.codex/config.toml):

[mcp_servers.canopy]
url = "http://127.0.0.1:45454/sse"
bearer_token_env_var = "CANOPY_API_KEY"

Kiro (.kiro/settings/mcp.json):

{
  "mcpServers": {
    "canopy": {
      "url": "http://127.0.0.1:45454/sse",
      "headers": { "Authorization": "Bearer ${CANOPY_API_KEY}" }
    }
  }
}

File Structure

canopy-mcp-consumer/
├── CLAUDE.md                              # Claude Code instructions
├── GEMINI.md                              # Gemini CLI instructions
├── AGENTS.md                              # Codex, OpenCode, Amp, Goose instructions
├── .clinerules                            # Cline instructions
├── .goosehints                            # Goose instructions
├── .mcp.json                              # Claude Code MCP config
├── .gemini/settings.json                  # Gemini CLI MCP config
├── .codex/config.toml                     # Codex CLI MCP config
├── opencode.json                          # OpenCode MCP config
├── .kiro/
│   ├── settings/mcp.json                  # Kiro MCP config
│   └── steering/canopy-orchestrator.md    # Kiro instructions
├── .amazonq/
│   ├── mcp.json                           # Amazon Q MCP config
│   └── rules/AGENTS.md                    # Amazon Q instructions (symlink)
└── MCP_TESTING_NOTES.md                   # Testing report

Canopy Concepts

A quick reference for the key concepts agents need to understand:

Concept Description
Agent An AI coding CLI (Claude, Gemini, Codex, OpenCode) running in a Canopy terminal
Terminal A PTY shell session — either a plain terminal or an agent session
Panel A UI container for a terminal, agent, browser, or note editor
Grid The main workspace area with resizable panels
Dock A minimized horizontal strip for monitoring background agents
Worktree A git worktree providing isolated file state per branch/task
Sidecar An embedded browser panel for viewing URLs, PRs, and docs inline
Action A typed, validated operation — every UI operation in Canopy is an action
MCP Tool An action exposed via MCP for external agents to call

Related

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors