How to Connect Swytchcode MCP Server: Setup Guide for Cursor, Claude Code, Windsurf & More

The Swytchcode MCP server is what lets AI coding editors like Cursor, Claude Code, and Windsurf see and use the tools available in your Swytchcode project. Once it's connected, your editor can discover what tools exist, understand how each one works, and run them directly, without you switching to a terminal or writing any extra integration code.

Getting connected only takes a handful of steps: install the Swytchcode CLI, sign in, set up your project, and point your editor at the server. The exact setup differs slightly from editor to editor, which is what this guide walks through, one editor at a time.

This is one of three ways to use Swytchcode. If you want the bigger picture first, see our guide on Different Ways to Use Swytchcode, which also covers the CLI and native SDKs.

What Is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI applications talk to external tools using a consistent interface. Instead of an AI editor generating raw HTTP requests or shell commands on its own, it sends a structured request to an MCP server, which handles tool discovery and execution.

In a Swytchcode project, the Swytchcode CLI acts as the MCP server. The flow looks like this:

AI Client → Swytchcode MCP Server → Swytchcode CLI → External APIs

Why Swytchcode Uses MCP

• One interface for every editor. Instead of separate integrations for Cursor, Claude Code, Windsurf, and others, Swytchcode exposes a single MCP interface that works the same way everywhere.
• Secure execution. Every request passes through the Swytchcode execution engine, which verifies the tool, validates the input, checks project policies, authenticates the integration, and then executes the request.
• Reliable tool discovery. Each enabled tool is exposed with its canonical ID, description, input schema, output schema, and documentation, so the AI client knows exactly what it can call.
• No editor lock-in. Switching editors does not require changing your project configuration.

Before You Start

You will need a terminal and, depending on your editor, admin access to install a CLI tool. No coding experience is required for the setup itself.

Step 1: Install the Swytchcode CLI

macOS / Linux

curl -fsSL https://cli.swytchcode.com/install.sh | sh

Windows (PowerShell)

irm https://cli.swytchcode.com/install.ps1 | iex

If you already have Node.js installed, you can use npm instead:

npm install -g swytchcode

swy works as a shorter alias for swytchcode in every command below. Verify the install:

swy --version

Step 2: Sign In

swy login

This opens a browser-based, device-flow login and stores your session for future CLI commands. Signing in is required before you can download integrations or connect authenticated services.

In CI or headless environments, set the SWYTCHCODE_TOKEN environment variable instead. The CLI only reads it from the process environment, not from .env files.

Step 3: Initialize Your Project

Navigate to your project folder and run:

cd /path/to/your/project
swy init

This creates a .swytchcode/ folder and a tooling.json file, which tracks the tools your project is allowed to use.

Step 4: Connect Your AI Editor

This is the part where the setup differs by editor. Most editors are configured automatically with a single command. A couple currently need one extra step through their own quickstart guide. Here is the exact method for each.

Cursor

swy init --editor=cursor

Automatically updates ~/.cursor/mcp.json.

Claude Code

swy mcp serve --claude

Automatically registers the Swytchcode MCP server with Claude Code. Note this uses a different command from the other editors below.

Windsurf

swy init --editor=windsurf

Automatically merges the connection into ~/.codeium/windsurf/mcp_config.json.

Windsurf is also the one editor with a documented manual option: open Settings → MCP Servers in Windsurf and add a new server with command swy mcp serve and transport stdio, if you would rather configure it by hand instead of running the command.

GitHub Copilot

swy init --editor=copilot

Creates .vscode/mcp.json and .github/copilot-instructions.md.

Hermes

swy init --editor=hermes

Automatically updates ~/.hermes/config.yaml.

OpenClaw

swy init --editor=openclaw

Automatically updates ~/.openclaw/settings.json.

Gemini CLI

swy init --editor=gemini

This prepares your project, but does not fully wire up the connection on its own. You will need to follow the Gemini CLI quickstart to complete the setup.

Codex

swy init --editor=codex

As with Gemini CLI, this prepares your project but does not complete the connection by itself. Finish the setup using the Codex quickstart.

Other MCP-Compatible Clients

If your client is not listed above, or you need a specific transport, run the server directly and point your client at it manually:

# Standard I/O (recommended for desktop editors)
swy mcp serve

# HTTP transport (remote or shared server)
swy mcp serve --transport http --port 5476

# Daemon (background) mode
swy mcp serve --transport http --port 5476 -d

Manual client configuration looks like this:

json

{
  "mcpServers": {
    "swytchcode": {
      "command": "swy",
      "args": ["mcp", "serve"]
    }
  }
}

If you use HTTP transport, it serves over http://127.0.0.1:<port>/sse on localhost only, and it requires a bearer token (stdio does not). Get the token with:

swy mcp token           # print the current token
swy mcp token --rotate  # invalidate it and generate a new one

Tool Profiles: Agent vs. Full

The MCP server exposes two different sets of tools, selected with --profile:

swy mcp serve --profile agent   # default: 7 tools, execution only
swy mcp serve --profile full    # 14 tools: adds init, bootstrap, get, doctor, plan, and more

• agent (default): a focused set for day-to-day coding assistants that only need to run tools already configured in your project: discover, info, exec, list, search, add, and read-only policy.
• full: everything in agent, plus setup and management tools like init, bootstrap, version, get, add_workflow, doctor, and plan. Use this if you want the AI client itself to install integrations or diagnose the project, not just execute existing tools.

Each MCP tool maps to an equivalent CLI command. See the MCP Reference for the full tool-by-tool table.

Step 5: Verify the Connection

The simplest check is to ask your editor or agent a direct prompt:

Connect GitHub and show me the tools available from the Swytchcode MCP server.

If the tools show up and the agent can list them, the connection is working. If nothing appears, confirm that the project you initialized is the one open in your editor, and that the CLI is signed in (swy whoami).

If you are running the server in daemon mode, check its status directly:

swy mcp status

You can also inspect the server with the official MCP Inspector:

npx @modelcontextprotocol/inspector ./swy mcp serve

A working connection means your AI client can discover available tools, inspect their schemas, execute enabled methods, run workflows, and receive structured responses back.

Troubleshooting

• No tools appear in the AI client. Check that the MCP server is running, that your project has enabled tools, that the correct project directory is open in your editor, and that the CLI is authenticated.
• Unable to connect to the MCP server. Confirm the configured command is exactly swy mcp serve. If you are using HTTP transport, verify the port in your client configuration matches the port the server is actually running on.
• Tool execution fails even though the client connects. Confirm the relevant integration has been authenticated, check that the tool has actually been added to your project, and review the CLI output for validation or policy errors.

For issues beyond this list, see the full Troubleshooting reference.

Frequently Asked Questions

1. What is the Swytchcode MCP server? It is the built-in server, part of the Swytchcode CLI, that exposes your project's trusted tools to MCP-compatible AI editors and agents using the Model Context Protocol.
2. Which AI editors does Swytchcode MCP support? Cursor, Claude Code, Windsurf, GitHub Copilot, Gemini CLI, Codex, Hermes, and OpenClaw, plus any other MCP-compatible client through manual configuration.
3. Do I need to write code to connect Swytchcode to my AI editor? No. Connecting an editor only requires CLI commands: install, sign in, initialize, and connect. Writing code is only needed if you choose to use the native SDKs instead of MCP.
4. Are all editors set up the same way? No. Cursor, Windsurf, Hermes, OpenClaw, and GitHub Copilot are configured automatically with one swy init --editor=<name> command. Claude Code uses a separate command, swy mcp serve --claude. Gemini CLI and Codex only get partially configured by swy init and need an extra step through their own quickstart guides to finish the connection.
5. Is there a manual configuration option? Yes. Windsurf has a documented manual path through Settings → MCP Servers. Any other MCP-compatible client can also be connected manually by running swy mcp serve and pointing the client at it with the JSON configuration shown above.
6. What is the difference between the agent and full tool profiles? The agent profile (default) exposes 7 execution-focused tools. The full profile exposes 14 tools, adding setup and management commands so the AI client can install integrations or diagnose the project itself.
7. How do I know if the MCP connection is working? Ask your AI client to list the tools available from the Swytchcode MCP server, run swy mcp status in daemon mode, or inspect the server with the official MCP Inspector.

Where to Go Next

• MCP Setup Quickstart: the condensed step-by-step version of this guide
• MCP Reference: complete server configuration, commands, and tool-by-tool mapping
• CLI Overview: how the CLI manages projects, integrations, and execution behind MCP
• Authentication: connecting your Swytchcode account and managing provider credentials
• Policy Rules: defining what tools are allowed to execute and when
• Retries and Idempotency: how Swytchcode handles failures during tool execution
• Cookbook: real-world agent workflows built on Swytchcode

Related reading: Different Ways to Use Swytchcode