# Windsurf MCP Setup in 2026: New Config Path, Rules, Fixes

> Windsurf MCP setup after the Devin Desktop rename: the mcp_config.json paths Devin Local reads, a working JSON entry, rules files and common error fixes.

- Author: [Serban Rusu](https://wingo-ui.com/blog/authors/serban), Founder of Wingo UI
- Published: Nov 6, 2026
- Category: [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents)
- Reading time: 10 min
- Canonical: https://wingo-ui.com/blog/windsurf-mcp

## TL;DR

Windsurf became Devin Desktop on June 2, 2026, and Cascade was removed on September 8, 2026, so MCP servers now belong to the Devin Local agent: ~/.config/devin/mcp_config.json for your user, .devin/mcp_config.json for a project. The old ~/.codeium/windsurf/mcp_config.json is still imported by default, which is why old guides seem to work. Add a stdio entry for npx -y wingo-ui@latest mcp, refresh the MCPs list, and put one rule in AGENTS.md that says to search the registry before writing UI.

Most Windsurf MCP guides you will find still tell you to edit `~/.codeium/windsurf/mcp_config.json`, open the MCPs menu in the Cascade panel and stay under 100 tools. Three things changed in 2026: Windsurf was renamed Devin Desktop on June 2, Cascade was removed on September 8, and MCP servers now belong to a new agent, Devin Local, with its own config files. This Windsurf MCP setup tutorial sorts out where the config lives today, what the JSON looks like, how to add a component registry (ours, Wingo UI) and the shadcn server, which rules file the agent reads, and the errors you are likely to hit.

What we checked, and how: on November 6, 2026 we read Cognition's docs at docs.devin.ai (where docs.windsurf.com now redirects): the Devin Desktop FAQ, the Devin Local and Devin CLI MCP, permissions and enterprise pages, and the stable changelog up to v3.11.238 (October 30, 2026). We did not install Devin Desktop for this post, so every path below is quoted from those docs, not from our disk. What we did run is our own side: our MCP server, which answered `tools/list` with 10 tools that day. Why a coding agent needs a component server at all is in our [component library MCP guide](https://wingo-ui.com/blog/component-library-mcp-guide).

## Is Windsurf still Windsurf?

The editor is. The name and the agent are not. Cognition's [Devin Desktop FAQ](https://docs.devin.ai/desktop/devin-desktop-faq) calls Devin Desktop "the new name for Windsurf", shipped as an over-the-air update on June 2, 2026, with settings, extensions and plans carried over. The agent changed later. The [stable changelog](https://docs.devin.ai/desktop/changelog) entry for v3.9.19 (September 8, 2026) says Cascade has been removed and Devin Local is the only agent available. Devin Local runs the same harness as the Devin CLI, so the CLI docs apply to it.

For MCP this matters more than the rename. Cascade read one file. Devin Local reads three scopes, imports configs from other tools, and asks before each tool call.

## Where is the Windsurf MCP config file now?

Per the [Devin Local customizations page](https://docs.devin.ai/desktop/devin-local/customizations) and the [MCP configuration docs](https://docs.devin.ai/cli/extensibility/mcp/configuration), as of November 6, 2026:

| Scope | File | In git? |
| --- | --- | --- |
| User | `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows) | No |
| Project | `.devin/mcp_config.json` | Yes, shared with the team |
| Local override | `.devin/mcp_config.local.json` | No, gitignored |
| Legacy Windsurf | `~/.codeium/windsurf/mcp_config.json` (`windsurf-next` for Next builds) | No, imported on start |

In the app, open the Agents window, click **Customize**, then the **MCPs** tab. With **This computer** picked in the **Install MCPs for** selector, the list shows the servers the agent loads for the folders open in that window. From there you can toggle a server, open its config file or refresh the list.

### Why do guides disagree on the path?

Because each one is right for a different year. `~/.codeium/windsurf/mcp_config.json` was the Cascade file. Devin Local still picks it up: the [configuration import docs](https://docs.devin.ai/cli/reference/configuration/read-config-from) list `~/.codeium/<channel>/mcp_config.json` under Windsurf, on by default. That is why an old guide can seem to work. It also means a server you remove from the new file can come back from the old one. If you want one source of truth, move your entries and turn the import off in `~/.config/devin/config.json`:

```json
{
  "read_config_from": {
    "windsurf": false
  }
}
```

That switch also stops `.windsurf/rules/` and `.windsurf/skills/` from loading. Leave it on if your rules still live there.

## What goes in the Windsurf MCP config JSON?

A map under `mcpServers`, one entry per server. A stdio entry has `command`, `args` and an optional `env`. A remote entry has `url`, an optional `transport` (`"http"` by default, `"sse"` for old servers) and optional `headers`. Both accept `"disabled": true`. Older guides show `serverUrl`: the legacy Cascade docs accepted it, the current docs use `url`.

This is the user-scope entry for our server:

```json
{
  "mcpServers": {
    "wingo-ui": {
      "command": "npx",
      "args": ["-y", "wingo-ui@latest", "mcp"]
    }
  }
}
```

Keep the `-y`. Without it npx stops to ask before it downloads the package, and nothing answers a server that the agent started in the background.

If you have the Devin CLI, it writes the same entry for you. The default scope is local, so pass `-s user` or `-s project`:

```bash
devin mcp add -s user wingo-ui -- npx -y wingo-ui@latest mcp
devin mcp list
```

## Remote entry or npx stdio: which is better?

Our server answers both ways. The stdio entry runs a small proxy that forwards to `https://wingo-ui.com/mcp` and adds the key that `npx wingo-ui@latest login` saved on your machine. The remote entry talks to the server directly:

```json
{
  "mcpServers": {
    "wingo-ui": {
      "url": "https://wingo-ui.com/mcp",
      "headers": { "Authorization": "Bearer wui_your_key" }
    }
  }
}
```

Put that one in `.devin/mcp_config.local.json` or the user file, never in the shared project file. The docs describe `${env:VAR}` and `${file:/path}` expansion for the OAuth fields; they do not say it applies to `headers` as of November 6, 2026, so assume the header is sent exactly as written. That is why we recommend stdio: the key stays in the CLI's login store or in `WINGO_UI_API_KEY`, outside every JSON file.

Without a key the proxy still connects. It logs `anonymous: docs only` to stderr and serves the same 10 read-only tools: `search_components`, `list_categories`, `get_component`, `get_block`, `get_design_rules`, `get_theme_tokens`, `get_install_instructions`, `check_updates`, `get_changelog` and `get_account_status`. Docs, props and search work; source needs a key from a free account for free items and a Pro account for Pro items. Every option is on the [MCP server docs](https://wingo-ui.com/docs/mcp).

## How do I add a Windsurf shadcn MCP server?

By hand, next to ours. The [shadcn MCP docs](https://ui.shadcn.com/docs/mcp) give setup steps for Claude Code, Cursor, VS Code and Codex, not Windsurf or Devin Desktop, as of November 6, 2026:

```json
{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["-y", "shadcn@latest", "mcp"]
    }
  }
}
```

The shadcn server browses, searches and installs from the registries configured in your `components.json`. With both libraries in one project, both ship a `button.tsx` with different props, so say in your rules which registry owns `components/ui`.

## Is there still a 100 tool limit?

Not one that is documented today. The cap of 100 tools across all servers was a Cascade rule; the [fast.io Windsurf guide](https://fast.io/resources/windsurf-mcp-setup-guide/) (updated February 9, 2026) still quotes it. Cascade is gone, and the Devin Local and Devin CLI MCP docs state no cap as of November 6, 2026. The budget that remains is context: every enabled tool sends its schema to the model on each turn. Disable servers you are not using with the toggle in **This computer** or `devin mcp disable <name>`.

What did change is approval. Devin Local asks before every MCP tool call by default, and the prompt lets you allow one tool or every tool on the server, for the session or always, per the [Devin CLI permissions docs](https://docs.devin.ai/cli/reference/permissions). To skip the prompt for a read-only server, add a pattern to `~/.config/devin/config.json` or the project's `.devin/config.json`:

```json
{
  "permissions": {
    "allow": ["mcp__wingo-ui__*"]
  }
}
```

Keep shell commands, including `npx wingo-ui@latest add`, on ask until you trust the result.

## What should the Windsurf rules say?

When to search, how to install, which tokens to use. Per the FAQ, Devin Desktop reads `AGENTS.md`, the legacy `.windsurfrules` and `.windsurf/rules/*.md`, plus the new `.devin/rules/*.md`, which wins when both folders exist. Rule files take `trigger` frontmatter: `always_on`, `glob`, `model_decision` or `manual`. Our CLI has no Devin target (`agents install` knows Claude Code, Codex, Gemini CLI, Grok and Cursor), so fetch the block it writes for Codex:

```bash
curl -s https://wingo-ui.com/agents/AGENTS.md >> AGENTS.md
```

It sits between `<!-- wingo-ui:start v=3 -->` and `<!-- wingo-ui:end -->` markers. Its core line:

```md
- Before writing UI, use the `wingo-ui` MCP tools: `search_components` to find what exists (blocks for whole screens), `get_component` / `get_block` for props and usage, `get_design_rules` for tokens, sizes, motion and mobile rules. Never recreate a component the library has.
```

`AGENTS.md` is also what Codex and Cursor read, so one file serves a mixed team. If your team already keeps Windsurf rules in `.windsurf/rules/`, they keep working; new rules go in `.devin/rules/`. Our [AGENTS.md vs CLAUDE.md comparison](https://wingo-ui.com/blog/agents-md-vs-claude-md-react) has a fuller template.

## Which prompts make the agent install real components?

Name the screen, the data and what you want reported back. The rule sends the agent to `search_components`, then `get_component` or `get_block`, then the install command. The prompt adds what a rule cannot: copy, routes and behavior.

### Prompt 1: a confirm dialog

```text
Add a delete confirmation to app/projects/[id]/settings with the Wingo UI dialog and button.
Read both with get_component first. The dialog names the project, uses the danger tone, cannot be
dismissed while the request runs, and shows a loading state on the Delete button. Install with the CLI.
```

The [Dialog](https://wingo-ui.com/components/dialog) and [Button](https://wingo-ui.com/components/button) are both free. A good result looks like this:

```tsx
// app/projects/[id]/settings/delete-project.tsx
"use client";

import { useState } from "react";
import { Trash2 } from "lucide-react";
import { Button } from "@/components/ui/button";
import { Dialog, DialogClose } from "@/components/ui/dialog";

type Props = { name: string; onDelete: () => Promise<void> };

export function DeleteProject({ name, onDelete }: Props) {
  const [open, setOpen] = useState(false);
  const [deleting, setDeleting] = useState(false);

  async function confirm() {
    setDeleting(true);
    try {
      await onDelete();
      setOpen(false);
    } finally {
      setDeleting(false);
    }
  }

  return (
    <Dialog
      open={open}
      onOpenChange={setOpen}
      dismissible={!deleting}
      tone="danger"
      icon={<Trash2 />}
      title={`Delete ${name}?`}
      description="This removes the project and its deployments. You cannot undo it."
      trigger={
        <Button variant="outline" tone="danger">
          Delete project
        </Button>
      }
      footer={
        <>
          <DialogClose asChild>
            <Button variant="soft" disabled={deleting}>
              Cancel
            </Button>
          </DialogClose>
          <Button tone="danger" loading={deleting} loadingText="Deleting" onClick={confirm}>
            Delete
          </Button>
        </>
      }
    />
  );
}
```

The parts a model writing from memory tends to miss are `dismissible`, which turns Escape and outside clicks into a small bump while the request runs, and the phone layout: below 768px the dialog opens as a bottom sheet with the actions stacked full width.

> Live demo (Dialog): Open the dialog, then narrow the window below 768px: the card becomes a bottom sheet you can drag down to close. Try it at [Dialog](https://wingo-ui.com/components/dialog) and install it with `npx wingo-ui@latest add dialog`.

### Prompt 2: a sign-in screen

```text
Build /login from the Wingo UI login-page block, card layout, password and 6 digit email code, no
social buttons. Post to our /api/auth routes and go to /dashboard on success. Replace every
Northwind string in the labels with Harbor and list each handler you left on its sample default.
```

The [Login Page](https://wingo-ui.com/components/login-page) ships sample handlers so its demo runs, and its default labels name Northwind CRM. That is why the prompt asks for a report: without `onVerifyCode`, the code view accepts the sample code 123456 for anyone. Check for `layout="card"`, `methods={["password", "otp"]}`, `showProviders={false}`, `labels` with `appName`, and real `onSignIn`, `onSendCode`, `onVerifyCode` and `onSuccess` handlers. A handler that throws an `Error` shows its message in the form. The full component with those handlers is in our [Gemini CLI shadcn setup](https://wingo-ui.com/blog/gemini-cli-shadcn-mcp).

> Live demo (Login Page): Type any email and a password shorter than 8 characters to see the error, then open Forgot password: the email carries over. Try it at [Login Page](https://wingo-ui.com/components/login-page) and install it with `npx wingo-ui@latest add login-page`.

### Prompt 3: swap a hand-written spinner

```text
Find every button in app/account that renders its own spinner while saving and replace it with the
Wingo UI button. Read its props with get_component first and show me the diff.
```

The Button's `loading` and `loadingText` props replace the spinner markup and the `disabled` juggling, and the width holds while it saves.

## What goes wrong, and how do I fix it?

- **The server is not in the MCPs list.** You edited a file the agent does not read for that folder, or the list has not reloaded since you saved. Check the scope table above and press refresh in **This computer**.
- **A server you deleted keeps coming back.** It still lives in `~/.codeium/windsurf/mcp_config.json`. Remove it there or set `read_config_from.windsurf` to `false`.
- **The stdio server fails to start.** Usually npx waiting for an install answer: add `-y`. Run the command in a terminal to see its own error.
- **A remote server will not connect.** Point `url` at the Streamable HTTP endpoint (usually `/mcp`). The client tries Streamable HTTP first and falls back to SSE on the same URL only after a 404 or 405, so for an SSE-only server set `"transport": "sse"`.
- **An OAuth server reports that it needs authentication.** Click **Authenticate** next to it in the list, or run `devin mcp login <name>`. Per the [Devin MCP overview](https://docs.devin.ai/cli/extensibility/mcp/overview), tokens from Windsurf or Claude Code are not shared, so you sign in once more here.
- **Server blocked on a team plan.** Enterprise admins can set allowlisted MCP servers and MCP registry URLs in the MCP/ACP controls under **Settings → Enterprise → Devin Desktop**, and those win over your local config. Ask them to add it.
- **Connected, but no source.** No key: run `npx wingo-ui@latest login` (a free account needs only an email) and refresh. The Button and Dialog are free; the Login Page is one of over 290 Pro items in a catalog of more than 360 ($8 a month, $80 a year or $150 once, on the [pricing page](https://wingo-ui.com/pricing)).

## Where should I start?

Create a free account, run `npx wingo-ui@latest login`, add the stdio entry to `~/.config/devin/mcp_config.json`, append the `AGENTS.md` block and try prompt 1 with the free Dialog and Button. The [coding agents docs](https://wingo-ui.com/docs/agents) cover the other agents, our [Antigravity MCP setup](https://wingo-ui.com/blog/antigravity-mcp), [Cursor shadcn setup](https://wingo-ui.com/blog/cursor-shadcn-mcp-rules) and [Codex MCP setup](https://wingo-ui.com/blog/codex-mcp-setup-react-ui) do the same for those editors, and the rest of the series is under [Building UI with AI agents](https://wingo-ui.com/blog/category/ai-agents).

## Components in this post

- [Button](https://wingo-ui.com/components/button) (Free): The React button component every screen starts with: five variants, six tones, all sizes, and a loading state that never jumps. Install: `npx wingo-ui@latest add button`
- [Login Page](https://wingo-ui.com/components/login-page) (Pro): A React login page with password, magic link or code sign-in, Google, Apple and Microsoft buttons, two-step codes and password recovery. Install: `npx wingo-ui@latest add login-page`
- [Dialog](https://wingo-ui.com/components/dialog) (Free): A React modal dialog for focused tasks: a spring-scaled card on desktop and a bottom sheet on phones, with nesting and scrolling. Install: `npx wingo-ui@latest add dialog`

## FAQ

### Where is the Windsurf MCP config file in 2026?

For the Devin Local agent in Devin Desktop (the new name of Windsurf) it is ~/.config/devin/mcp_config.json for your user, %APPDATA%\devin\mcp_config.json on Windows, and .devin/mcp_config.json or .devin/mcp_config.local.json in a project. The legacy ~/.codeium/windsurf/mcp_config.json is still imported by default, per Cognition's docs as of November 6, 2026.

### Does Windsurf still have a 100 tool limit for MCP?

The 100 tool cap was a documented Cascade limit, and Cascade was removed from Devin Desktop on September 8, 2026. The current Devin Local docs state no tool cap as of November 6, 2026, but every tool schema still costs context, so keep only the servers you use switched on.

### Should a remote server use serverUrl or url?

Use url. The Devin CLI and Devin Local docs list url with an optional transport and headers; serverUrl comes from the legacy Cascade docs, which accepted both.

### Does the shadcn MCP server work with Windsurf?

Yes, as a manual stdio entry with command npx and args -y, shadcn@latest, mcp. The shadcn MCP docs do not list Windsurf or Devin Desktop as of November 6, 2026, so you add the entry by hand.

### Are .windsurfrules and .windsurf/rules still read?

Yes. Devin Desktop still reads .windsurfrules, .windsurf/rules/*.md and AGENTS.md, and prefers .devin/rules/*.md when both rule folders exist, according to its FAQ as of November 6, 2026.

---

Source: https://wingo-ui.com/blog/windsurf-mcp