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 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 three profiles, selected with swy mcp serve --profile agent|operator|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).

For personal agents (Hermes, OpenClaw, ZeroClaw) driven from a chat. Everything in the agent profile, plus the tools to set integrations up, add stricter policies and connect accounts. See Personal agents.

MCP Tool	CLI Equivalent	Purpose
`swytchcode_get`	`swy get`	Fetch a provider’s bundles.
`swytchcode_policy_check`	`swy policy validate`	Check a draft policy without saving it.
`swytchcode_policy_add`	-	Save a new, stricter policy: blocking actions, `REQUIRES_APPROVAL`, `REDACT` or `TRUNCATE`. Refuses an existing id (there is no `replace`), `ALLOW` and `MODIFY` policies, and `notify` alerts, with the command a person runs instead.
`swytchcode_connect`	`swy auth connect`	Takes only a provider name. OAuth: returns a one-time link for the user to open. API key, basic auth and signed requests: returns the `swy auth connect` command to run on the machine, so a key never goes through the chat.

In this profile, swytchcode_policy ends with the command a person runs to remove a policy (cd <project> && swytchcode policy remove <id>). The server also tells the agent, in its MCP instructions, never to remove, loosen or work around a policy. swytchcode_exec refuses demo (its responses are simulated) and allow_raw. When a provider isn’t connected, or rejects the call with a 401, the error’s suggested_action points the agent at swytchcode_connect.

Results that need a person carry an action object for the agent to pass on as is:

{
  "action": {
    "kind": "connect",
    "message": "stripe isn't connected yet. Open this link to connect it, then tell me when it's done. It's a one-time link - don't forward it.",
    "url": "https://..."
  }
}

kind is connect (open url), connect_terminal (run command on the machine) or needs_person (a change the agent may not make; command makes it).

Full profile (17 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.

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 17 tools instead of the default 7-tool agent profile.
`swy mcp serve --profile operator --project <dir>`	Start the personal-agent profile in that project, whatever directory the agent starts it from.
`swy mcp serve --tenant <id>`	Run every call for one end user of your app (any profile). No tool takes a tenant argument.
`swy mcp serve --transport http --port 5476`	Start the MCP server over HTTP/SSE at `http://127.0.0.1:<port>/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:

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 for the full per-editor breakdown). Claude Code, Hermes and OpenClaw are registered through their own CLI (claude mcp add, hermes mcp add, openclaw mcp set) instead of a file merge. Hermes and OpenClaw run only when init runs in a terminal; otherwise init prints the command.

MCP architecture

End-to-end flow diagram

┌───────────────────────────────────────────────────────────────────────┐
│ 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.

Browse all examples

Zoom via MCP

Drives Zoom entirely through Swytchcode as an MCP server in Claude, Cursor, Codex, Copilot, or Windsurf.

Connect AI Clients

Set up the MCP server for Cursor, Claude Code, Windsurf, and other editors.

CLI Overview

Explore the core concepts and architecture of the Swytchcode CLI.

Command Reference

Every swy subcommand, flag, and exit code.