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

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.

Is Windsurf still Windsurf?

The editor is. The name and the agent are not. Cognition's Devin Desktop FAQ (opens in a new tab) 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 (opens in a new tab) 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 (opens in a new tab) and the MCP configuration docs (opens in a new tab), as of November 6, 2026:

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 (opens in a new tab) 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:

{
  "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:

{
  "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:

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:

{
  "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.

How do I add a Windsurf shadcn MCP server?

By hand, next to ours. The shadcn MCP docs (opens in a new tab) give setup steps for Claude Code, Cursor, VS Code and Codex, not Windsurf or Devin Desktop, as of November 6, 2026:

{
  "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 (opens in a new tab) (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 (opens in a new tab). To skip the prompt for a read-only server, add a pattern to ~/.config/devin/config.json or the project's .devin/config.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:

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:

- 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 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

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 and Button are both free. A good result looks like this:

// 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.

Prompt 2: a sign-in screen

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 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.

Prompt 3: swap a hand-written spinner

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 (opens in a new tab), 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).

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 cover the other agents, our Antigravity MCP setup, Cursor shadcn setup and Codex MCP setup do the same for those editors, and the rest of the series is under Building UI with AI agents.

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.