AI Tools (MCP)

Corral speaks the Model Context Protocol (MCP) — the open standard AI coding tools use to talk to outside systems. Point your AI assistant at Corral’s MCP server and it sees what Corral sees: which projects are registered, what’s running and on which URL, the connection string for every local service, recent logs, and more — over a typed protocol the agent already knows how to call, instead of shelling out to the CLI and parsing text.

One server reaches every client. An agent working in a Corral-managed project can answer “what’s my dev URL?”, “is Postgres up and what’s its connection string?”, or “why did the build fail?” without leaving its tools — and it can start, stop, or restart things after a change instead of asking you to.

Supported AI clients

Corral knows how to configure seven clients today. Installing writes one corral entry into each client’s native MCP config — nothing else in the file is touched.

Client	User-scope config	Project-scope config
Claude Code	~/.claude.json	.mcp.json
Cursor	~/.cursor/mcp.json	.cursor/mcp.json
VS Code	~/Library/Application Support/Code/User/mcp.json	.vscode/mcp.json
Codex CLI	~/.codex/config.toml	.codex/config.toml
Continue.dev	~/.continue/config.yaml	.continue/config.yaml
Zed	~/.config/zed/settings.json	(none)
Windsurf	~/.codeium/windsurf/mcp_config.json	(none)

Setup

Via the macOS app

First-run setup includes a Configure AI clients step that detects your installed AI tools and offers a checkbox to wire each one up.

Anytime after, open Settings → AI Tools. Each detected client shows its status — configured, not configured, mismatched, or unparseable — with add and remove buttons, plus a test-connection action.

Via the CLI

corral mcp install                  # configure every detected AI client (user scope)
corral mcp install --client cursor  # configure just one client
corral mcp install --project        # write project-scoped config in the current directory
corral mcp status                   # show each client's configuration status
corral mcp uninstall                # remove Corral's entry from every detected client
corral mcp uninstall --client zed   # remove from just one client

With no --client, install and uninstall act only on the clients actually detected on your machine. Pass --client <name> to force a specific one — claude-code, cursor, vscode, codex, continue, zed, or windsurf — even if it isn’t installed yet.

--project writes config scoped to the current directory instead of your user-global config — handy for committing .cursor/mcp.json or .mcp.json into a repo. Zed and Windsurf have no project scope. Both commands exit non-zero if any client couldn’t be configured, so they’re safe to chain in scripts.

You never run the bare corral mcp (server mode) yourself — your AI client spawns it. See the CLI reference for the full command surface.

What an agent can do

Corral exposes its capability surface as MCP tools, grouped by domain. Tools that wrap Pro features are marked PRO.

Projects

Tool	What it does
project_list	List every registered project with status
project_info	Full detail for one project: dev URL, port, framework, attached services, settings
project_for_path	Map a working directory to its registered project — the foundation other project tools chain off
project_scan	Discover JS/TS projects under a directory
project_add · project_remove	Register or unregister a project
project_settings_update	Change per-project settings

Lifecycle

Tool	What it does
start_project · stop_project · restart_project	Control a single dev server
up · down	Bring the whole environment (DNS + reverse proxy + auto-start projects) up or down
infra_status	DNS, reverse proxy, and daemon health

Services PRO

Tool	What it does
service_catalog	List installable services
services_list	Installed services with status, version, ports, connection string
service_info	Detail for one service
service_install · service_uninstall	Install or remove by name or name@version
service_start · service_stop · service_restart	Service lifecycle
service_config_update	Update ports, env, or version pinning

Stacks

Tool	What it does
stack_list	Every stack with aggregate status, origin (manual / cloudflare), and member count
stack_info	One stack’s members, wiring, and status
stack_start · stack_stop PRO	Bring a whole stack — its projects and services — up or down

Sharing

Tool	What it does
share_start	Start a Cloudflare tunnel that exposes a project to the internet
share_stop · share_status	Stop or query a tunnel

Logs

Tool	What it does
logs	Query log snapshots — across all units or one project, with a search term and limit

Node.js

Tool	What it does
node_list · node_install	List or install Node.js versions

Frameworks & git

Tool	What it does
frameworks_list	Supported frameworks and their detection rules
effective_dev_command	The exact command Corral will run for a project
git_branch	Current branch for a project

Read-only

Tool	What it does
license_info	Tier, entitlements, expiry
settings_show	App-wide settings

Diagnostics

Tool	What it does
report_problem	File a bug report with the maintainers. Consent-first — diagnostics are opt-in (off by default), and the agent must show you the message and bundle contents first. See Reporting Problems

How it works

The installer adds a single entry — keyed corral — to each client’s MCP config:

{
  "corral": {
    "command": "/usr/local/bin/corral",
    "args": ["mcp"]
  }
}

The absolute path is deliberate: GUI-launched editors don’t inherit your shell PATH, so a bare corral wouldn’t resolve. When the client starts, it runs corral mcp, which speaks JSON-RPC over stdio.

The MCP server is stateless. It holds no state of its own and forwards every tool call to Corral’s background daemon — the same daemon the CLI and macOS app use. So an agent always sees the same running state you do, multiple AI clients can connect at once, and the server simply exits when the client closes. All the real logic lives in the daemon; MCP is just a third way in.

Free vs Pro tools

MCP is a delivery channel, not a paywall. The server is free, and most tools work on every tier — projects, lifecycle, logs, Node.js, git, frameworks, read-only introspection, and reporting problems.

The tools that wrap Pro features inherit the daemon’s Pro gate: the nine service tools (the service_* family plus services_list), plus the two stack lifecycle tools (stack_start / stack_stop — reads like stack_list / stack_info stay free). Called on the free tier, they return a clean “activate Corral Pro” message that points at how to upgrade — so the agent can tell you exactly what’s needed instead of failing cryptically. Activate a license from the Subscription room or with corral license activate.

Troubleshooting

Symptom	What to do
The agent doesn’t see Corral’s tools	Run corral mcp status and confirm the client reads configured. Restart the AI client after installing — most read their MCP config only at startup.
Status shows mismatched	The client’s corral entry points somewhere else (often a stale path from an older install). Re-run corral mcp install --client <name> to update it.
Status shows error	Corral couldn’t read that config file (e.g. a permissions problem) — the path and reason are printed so you can fix it. This is surfaced rather than hidden as “not configured.”
A tool returns an activation message	That tool wraps a Pro feature; activate a license.