Connecting Windsurf to Your Strapi CMS via MCP

The open-source headless CMS Strapi 5 5.47.0 and later exposes an /mcp endpoint that AI clients can call directly. Point Windsurf at it by adding a serverUrl entry to mcp_config.json with an Admin token in the Authorization header, and Cascade can list, create, update, and publish entries inside the permissions that token carries.

Managing content in a browser tab while writing code in Windsurf creates a repetitive loop: draft an article in the Admin Panel, switch back to the editor, alt-tab again to publish, repeat. A Model Context Protocol (MCP) server setup removes that loop by connecting Windsurf directly to Strapi.

The Windsurf MCP side is one config object in Strapi and one JSON block on your machine, provided your project is on a recent enough version. After that, you can create, update, and publish entries with prompts in Cascade.

In brief

• Use Strapi 5.47.0 or later for the built-in MCP server.
• Turn on the mcp object in your Strapi server configuration.
• Create a scoped Admin token with only the permissions Cascade needs.
• Add the Strapi endpoint and token to Windsurf's mcp_config.json file.

What Is MCP and Why Set It Up for Windsurf?

MCP is an open protocol that standardizes how applications expose tools and data to language models. It also standardizes how they expose prompts, using the JSON-RPC message format. An MCP server is a service that declares a set of callable tools within the MCP server architecture.

An MCP client (in this case, Windsurf's Cascade agent) discovers those tools through MCP tool discovery and lets the model invoke them during a conversation. A Windsurf MCP connection to Strapi means Cascade can call Strapi's content operations, such as create and publish, the same way it calls any other tool.

How Windsurf Uses MCP Servers

Windsurf reads its MCP server definitions from ~/.codeium/windsurf/mcp_config.json and connects to each defined server using the supported MCP transports. At connection time, Cascade sends a tools/list request to enumerate what each server offers, then surfaces those tools in the Cascade tool panel. When you send a prompt, the model can issue a tools/call request automatically, and the server executes the tool and returns the result.

Why Use Strapi's Built-In MCP Server

Strapi 5 ships a first-party server with no third-party wrapper or community npm package needed. It exposes content management tools for your Content-Types, and every tool is gated by the permissions of the Admin token used to connect. The feature is built in and works in both Development and Production environments. Since the server lives inside Strapi itself, it uses the same permission model the Admin Panel enforces. This avoids an additional permission layer to audit.

Prerequisites for MCP Server Setup

You need:

• A running Strapi 5 project on version 5.47.0 or later. The MCP server shipped in beta at 5.47.0 and went GA at 5.49.0, so if you're upgrading an older project, check your version first.
• Node.js 20 or higher, which is Strapi 5's general system requirement.
• Windsurf with Cascade installed. Strapi's docs publish no minimum Windsurf version for MCP.
• Permission to create Admin tokens in the Strapi Admin Panel (Super Admin, or a role granted that permission).

How to Activate the Strapi Server

Strapi must serve the /mcp endpoint and have a token available before Windsurf can connect.

Add the MCP Object to Your Server Configuration

Add an mcp object to your server configuration file. In JavaScript (config/server.js):

// config/server.js
module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
  mcp: {
    enabled: true,
  },
});

Or in TypeScript configuration (config/server.ts):

// config/server.ts
import type { Core } from '@strapi/strapi';

const config = ({ env }: Core.Config.Shared.Params): Core.Config.Server => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
  mcp: {
    enabled: true,
  },
});

export default config;

Restart Strapi after saving. The MCP endpoint becomes available at /mcp, so a local project answers at http://localhost:1337/mcp. Browser probes may return an error because the endpoint accepts only POST.

Create an Admin Token in the Admin Panel

The MCP server accepts Admin tokens; API tokens are rejected. The two token types are strictly separated, and each is rejected on the other's routes.

To create one:

1. Go to Settings → Administration Panel → Admin Tokens.
2. Click Create new Admin Token.
3. Fill in a name and an optional description. Then choose a token duration (7 days, 30 days, 90 days, or Unlimited).
4. Define permissions by browsing the tabs and toggling checkboxes. You can't grant permissions you don't hold yourself; those appear disabled.
5. Click Save. The token is displayed once, with a copy button. Copy it now, because the plaintext key is shown only once, immediately after creation or regeneration.

The permissions you check here decide exactly which MCP tools Windsurf will see. If the token only grants read on an Article Content-Type, the AI client will only see listing and reading tools for articles. Scope the token to what your prompts actually need, and nothing more.

Configure Advanced MCP Options (Optional)

Two optional keys tune the server's timing behavior:

The defaults work for most local setups. If prompts against large datasets start timing out, raising requestTimeoutMs is the knob to try first.

MCP Server Setup: Connecting Windsurf to Strapi

Edit Your mcp_config.json File

Open ~/.codeium/windsurf/mcp_config.json (on Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json) and add the Strapi entry:

File: ~/.codeium/windsurf/mcp_config.json

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "strapi-mcp": {
      "serverUrl": "http://localhost:1337/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

Replace YOUR_ADMIN_TOKEN with the Admin token you copied earlier. Use serverUrl for HTTP servers and the command/args pair for stdio-based servers. Windsurf rejects the url field in this entry.

Windsurf supports environment variable interpolation to keep a plaintext token out of the config file:

File: ~/.codeium/windsurf/mcp_config.json

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "strapi-mcp": {
      "serverUrl": "http://localhost:1337/mcp",
      "headers": {
        "Authorization": "Bearer ${env:STRAPI_ADMIN_TOKEN}"
      }
    }
  }
}

Verify the Connection in Windsurf

After editing the config, reload through Cascade's MCP settings: click the hammer icon in Cascade's top-right menu, choose Configure, then hit Refresh in the MCP toolbar. Alternatively, use the Command Palette option to run "Windsurf: Configure MCP Servers" (Cmd+Shift+P, or Ctrl+Shift+P on Windows and Linux).

Once reloaded, strapi-mcp should appear in Cascade's MCP section with a green dot indicating a connected status. Click the hammer icon to see the list of tools the server exposed. If you see tools for exactly the Content-Types and actions your token permits, the connection is working as designed.

Using Strapi's Tools in Windsurf

With the connection live, Cascade can read and write your Strapi content directly from the editor.

Available Content Management Tools

The available tools depend on the Content-Type, its settings, the environment, and the token:

• Collection Types. Each Collection Type exposes up to eight tools: list, get, create, update, delete, publish, unpublish, and discard_draft. The last three only appear when Draft and Publish is active on that Content-Type.
• Single Types. Single Types expose up to six tools. They omit list, and a single write tool handles both creation and updates: it creates the document if none exists or updates the existing draft.
• Permission filtering. The token determines the actual tool count. No delete permission means no delete tool in Cascade's list, and no publish permission means none of the three Draft and Publish tools show up.
• Listing options. The list tool supports pagination options (page defaults to 1, pageSize defaults to 25 with a max of 100) plus sorting and Strapi's filter operators, both constrained to scalar attributes, so you can't sort by a relation or a media field.
• Development utility. In development mode, a log utility tool is also available for writing to the Strapi server console; it requires no admin permissions.
• Tool ceiling. Cascade has a 100-tool ceiling. A project with many Collection Types, each with Draft and Publish active, can generate a lot of tools at eight per type. A token scoped to only the Content-Types the AI needs keeps the count down.

Managing Content With Natural Language Prompts

Cascade selects and calls the appropriate tool from your natural-language description. Prompt examples include:

• "Create a new article titled 'Hello' with body 'First post'." invokes create and produces a draft entry (assuming Draft and Publish is on).
• "List the five most recent articles." invokes list and returns a paginated result, newest first.
• "Publish article abc123." invokes publish against that document ID and flips the entry to published.
• "Update article abc123, change the title to 'Hello Strapi'." invokes update and touches only the title field.

For localized content, phrase the locale explicitly. "Create an article in French with the title 'Bonjour le monde'" gets Cascade to pass locale: fr correctly, whereas a French-looking title alone leaves the model guessing.

Configuring Permissions and Security

The MCP server enforces a scoped token's permissions during tool discovery, schema filtering, locale filtering, and execution:

1. Tool visibility. Only tools the token permits are exposed at connection time.
2. Field filtering. Input and output schemas are narrowed to accessible fields. If the token grants read on Article but excludes the body field, the AI client will not see or receive body content. Write schemas likewise only include fields permitted for that action.
3. Locale filtering. With Internationalization (i18n) active, the locale parameter is narrowed per action. A token might allow reading in en and fr but creating only in en.
4. Runtime enforcement. Each handler calls Strapi's permission checker on the specific document at execution time. Condition-based rules, such as "only update entries you own," are enforced here even if the schema allowed the call.

Create dedicated Admin tokens for each AI client or use case, with the most restrictive permissions that still allow the AI to accomplish its task. Supported patterns include read-only access. You can also limit a token to articles but not categories and restrict specific fields or locales. And if your organization runs the Enterprise plan on 5.52.0 or later, MCP entry actions land in the Audit Logs with an origin key set to mcp, so you can tell AI-triggered writes apart from Admin Panel activity.

Troubleshooting Guide for Your MCP Server Setup

Most connection problems trace back to one of a handful of causes:

• Windsurf shows strapi-mcp as disconnected after you edit the config. Windsurf needs a reload. Restart it or click Refresh in the MCP toolbar. Validate the whole JSON file.
• /mcp returns 404 or connection refused. Either mcp: { enabled: true } isn't in your server config, or Strapi wasn't restarted after you added it.
• GET or DELETE on /mcp returns 405 Method Not Allowed. A 405 response is expected. The Streamable HTTP transport uses POST for both initialization and tool calls, so a browser visit or curl -X GET will always get a 405.
• No tools appear for a Content-Type. The token lacks permissions for it. Re-check the token in Settings → Administration Panel → Admin Tokens.
• You revoked or changed a token but Cascade still lists the old tools. Start a new Cascade session. Each POST re-authenticates from scratch.

That last point reflects the stateless architecture: every request creates a fresh, ephemeral MCP server instance scoped to the token, with no session persistence between requests. Permission changes apply on the next request without a Strapi restart.

Known Limitations to Be Aware Of

Strapi 5.52.1 has these documented limitations:

• No media upload through MCP. Media fields accept references to existing assets, but the server can't upload new files. Add files through the Media Library or upload API first, then reference them in tool calls.
• Dynamic Zones are untyped. Dynamic Zone fields pass through as untyped arrays. The internal structure of each component isn't described in the tool schemas, so Cascade gets less guidance when writing to them.
• No nested population. The list and get tools don't support nested population parameters for relations.
• Custom fields may degrade. Plugin-registered custom fields map to their underlying Strapi type, and fall back to unknown if the custom field registry isn't populated when tools are registered.
• Circular component references fall back to an open record<string, unknown> schema at the point of the cycle.

Plan around these constraints when deciding which content workflows to move into Cascade.

Try the Windsurf Setup on Staging

The full setup requires two files and a token. Turn on mcp in your Strapi server config. Then generate a scoped Admin token and point mcp_config.json at http://localhost:1337/mcp. From there, prompts in Cascade can draft, list, update, and publish entries. The four-level permission model keeps the AI inside the boundaries you set. If you have a Strapi 5 project on 5.47.0 or later, try it against a staging instance with a read-only token, then widen permissions as the workflow proves itself.