# MCP Reference This page focuses on the MCP-specific commands and tools exposed by the Swytchcode CLI. Use it alongside the [MCP Server setup guide](/cli/mcp/) for editor configuration and connection walkthroughs. Commands below are shown with `swy`, the shorter alias for `swytchcode` (e.g. `swy mcp serve` is the same as `swytchcode mcp serve`). --- ## MCP tools reference The Swytchcode MCP server exposes tools under two profiles, selected with `swy mcp serve --profile agent|full` (`agent` is the default). ### Agent profile (7 tools) Focused set for AI agents at task-execution time - no setup/management tools. | MCP Tool | CLI Equivalent | Purpose | |----------|----------------|---------| | `swytchcode_discover` | `swy discover` | Find API capabilities by natural-language intent. Start here when you don't know which tool to call. | | `swytchcode_info` | `swy info` | Get the input/output schema for a tool by canonical ID. | | `swytchcode_exec` | `swy exec` | Execute a tool by canonical ID. Supports `dry_run`, `demo`, and `explain` modes. | | `swytchcode_list` | `swy list` | List locally available tools and integrations. No registry calls. | | `swytchcode_search` | `swy search` | Search the remote registry for integrations. | | `swytchcode_add` | `swy add method` | Enable an already-installed tool by canonical ID. | | `swytchcode_policy` | `swy policy list` | List configured execution guard policies (read-only). | ### Full profile (15 tools) Everything in the agent profile, plus setup and management tools for developers and power users. | MCP Tool | CLI Equivalent | Purpose | |----------|----------------|---------| | `swytchcode_init` | `swy init` | Initialize Swytchcode in this project: creates `.swytchcode/`, `tooling.json`, and editor-specific config. | | `swytchcode_bootstrap` | `swy bootstrap` | Fetch all integrations declared in `tooling.json` that aren't already installed. | | `swytchcode_version` | `swy -v` | Get the current Swytchcode version. | | `swytchcode_get` | `swy get` | Fetch and install integration bundles (methods only) for a project. | | `swytchcode_doctor` | `swy doctor` | Run local diagnostics: tooling, bundles, manifest, base URLs, and auth posture. CI-friendly. | | `swytchcode_policy_check` | `swy policy validate` | Check a draft policy without saving it: errors, warnings, a plain-English summary, and optionally what it would do to a sample call (block, pause, allow, change, or - with `"$response"` in `test_args` - redact or cut the response). Runs the draft's `tests` with the rest of `policies.json`. | | `swytchcode_policy_add` | `swy policy add` | Save a policy to `policies.json`. Accepts every version-2 feature. Refuses a policy with errors or failing `tests`, and an existing id unless `replace: true`. | | `swytchcode_policy_remove` | `swy policy remove` | Remove a policy by id. | These MCP tools mirror the same CLI execution engine used in the terminal. `swytchcode_add`, `swytchcode_discover`, `swytchcode_exec`, and `swytchcode_info` are registered in both profiles with profile-appropriate descriptions. `swytchcode_exec` with `dry_run` runs every policy on the call without sending it, so an agent can check a call first. Policy errors include `hint` (what to do instead) and, for limits, `retry_after`; changes made by `MODIFY`, `REDACT`, or `TRUNCATE` are listed in the result's `policy_notes`. In `swytchcode_policy_check`, `test_args` keys starting with `$` set built-in fields (e.g. `"$env": "production"`), and `"$response"` / `"$status_code"` give a response for response policies. A check starts from no earlier calls and changes no real counts. The policy write tools (`swytchcode_policy_check`, `swytchcode_policy_add`, `swytchcode_policy_remove`) exist only in the `full` profile. They are meant for building: a developer, or a coding agent they supervise, writing `policies.json`. An agent running with the `agent` profile can only list policies, never change them. See [Writing policies with a coding agent](/policies/overview/#write-policies-with-a-coding-agent). --- ## MCP server management commands The CLI exposes these lifecycle commands for the MCP server. | Command | Purpose | |---------|---------| | `swy mcp serve` | Start the MCP server in the foreground over stdio (default transport). | | `swy mcp serve --profile full` | Start with all 15 tools instead of the default 7-tool agent profile. | | `swy mcp serve --transport http --port 5476` | Start the MCP server over HTTP/SSE at `http://127.0.0.1:/sse`, localhost-only. | | `swy mcp serve -d --transport http` | Start the MCP server as a background daemon (daemon mode requires HTTP transport). | | `swy mcp serve --claude` | Register this server with Claude Code automatically via `claude mcp add` (requires the `claude` CLI on `PATH`; stdio transport only). | | `swy mcp status` | Check whether the daemon is running. | | `swy mcp stop` | Stop the daemon. | | `swy mcp token [--rotate]` | Print the MCP HTTP bearer token (required for HTTP transport only; stdio needs no token). Stored at `~/.swytchcode/mcp_token`. | You can also pair these commands with editor initialization (`swy init`), which registers the server (stdio transport) automatically: ```bash swy init --editor=cursor --mode=sandbox swy init --editor=claude --mode=sandbox swy init --editor=codex --mode=sandbox swy init --editor=copilot --mode=sandbox swy init --editor=gemini --mode=sandbox swy init --editor=hermes --mode=sandbox swy init --editor=openclaw --mode=sandbox swy init --editor=windsurf --mode=sandbox ``` Each editor writes its own config file/format (see the `init` section of the [command reference](/reference/commands/) for the full per-editor breakdown). Claude Code is the one exception that isn't a plain file merge - it's registered by shelling out to the `claude` CLI itself, since Claude Code's own config format/location isn't meant to be hand-written. --- ## MCP architecture ### End-to-end flow diagram ```text ┌───────────────────────────────────────────────────────────────────────┐ │ AI Client / IDE │ │ e.g. Cursor, Claude Code, Codex, Copilot, Gemini, Hermes, OpenClaw, │ │ Windsurf │ └───────────────────────┬───────────────────────────────────────────────┘ │ │ MCP request ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ Swytchcode MCP Server │ │ Exposes tools such as swytchcode_list, swytchcode_get, and │ │ swytchcode_exec │ └───────────────────────┬───────────────────────────────────────────────┘ │ │ CLI call / structured execution ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ Swytchcode CLI │ │ Resolves project state, tool schemas, auth, and policies │ └───────────────────────┬───────────────────────────────────────────────┘ │ │ Approved API call ▼ ┌───────────────────────────────────────────────────────────────────────┐ │ External APIs / Integration Providers │ │ Stripe, GitHub, and other supported integrations │ └───────────────────────────────────────────────────────────────────────┘ ``` This keeps the AI client decoupled from direct API logic while preserving a single secure execution path across all supported editors. --- ## Related pages - [Zoom via MCP](https://github.com/swytchcodehq/swytchcode-examples/tree/main/zoom-swytchcode-demo) - Drives Zoom entirely through Swytchcode as an MCP server in Claude, Cursor, Codex, Copilot, or Windsurf. - [Connect AI Clients](https://docs.swytchcode.com/cli/mcp/) - Set up the MCP server for Cursor, Claude Code, Windsurf, and other editors. - [CLI Overview](https://docs.swytchcode.com/cli/overview/) - Explore the core concepts and architecture of the Swytchcode CLI. - [Command Reference](https://docs.swytchcode.com/reference/commands/) - Every swy subcommand, flag, and exit code.