MCP 服务器

5.47.0

Page summary:
Strapi 包含一个内置的模型上下文协议 (MCP) 服务器。一旦启用，它允许 AI 客户端通过 Strapi 的内容管理器直接创建、读取、更新、删除、发布和取消发布内容。所有操作都受管理员令牌权限的控制。
🌐 Strapi includes a built-in Model Context Protocol (MCP) server. Once enabled, it lets AI clients create, read, update, delete, publish, and unpublish content directly through Strapi's Content Manager. All operations are gated by Admin token permissions.

MCP 服务器向 AI 客户端（比如 Claude Desktop、Claude Code、Codex、Cursor 或任何兼容 MCP 的工具）提供一套内容管理工具。连接到 MCP 服务器的 AI 客户端可以做的事情包括创建博客文章、列出最近的条目或发布页面。可使用哪些工具取决于用于身份验证的管理员令牌所授予的权限。

🌐 The MCP server exposes a set of content management tools to AI clients such as Claude Desktop, Claude Code, Codex, Cursor, or any MCP-compatible tool. An AI client connected to the MCP server can, for example, create a blog article, list recent entries, or publish a page. Which tools are available depends on the permissions granted to the Admin token used for authentication.

计划

免费功能

角色与权限

管理员（令牌创建者）

激活

服务器配置

环境

可在开发和生产环境中使用

配置

🌐 Configuration

在首次使用之前，必须对 Strapi MCP 服务器进行：

🌐 Before first use, the Strapi MCP server must be:

通过服务器配置文件启用，并使用在管理面板中创建的管理员令牌进行身份验证
已连接到你的 AI 客户端。

基于代码的 Strapi 配置

🌐 Strapi code-based configuration

通过将 mcp 对象添加到服务器配置文件中来启用 MCP 服务器：

🌐 Enable the MCP server by adding the mcp object to the server configuration file:

JavaScript
TypeScript

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,
  },
});

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

const config = ({ env }: Core.Config.Shared.ConfigParams): 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;

设置完成后，重启 Strapi。MCP 端点将在你的 Strapi 服务器上通过 /mcp 可用（例如，http://localhost:1337/mcp）。

🌐 Once the setting is in place, restart Strapi. The MCP endpoint becomes available at /mcp on your Strapi server (e.g., http://localhost:1337/mcp).

高级选项

🌐 Advanced options

可以将以下可选键添加到 mcp 配置对象中：

🌐 The following optional keys can be added to the mcp configuration object:

选项	类型	默认值	描述
`enabled`	布尔值	`false`	启用或禁用 MCP 服务器。
`connectTimeoutMs`	数字	`5000`	内部 MCP 传输在请求中止前的最大连接时间（毫秒）。
`requestTimeoutMs`	数字	`60000`	单个 MCP 请求在超时前完成的最大时间（毫秒）。

config/server.js
mcp: {
  enabled: true,
  connectTimeoutMs: 10000, // 10 seconds
  requestTimeoutMs: 120000, // 2 minutes
},

Strapi 管理面板配置

🌐 Strapi admin panel configuration

MCP 服务器使用管理员令牌对请求进行身份验证。每个 MCP 会话的权限范围取决于用来连接的令牌：

🌐 The MCP server authenticates requests using Admin tokens. Each MCP session is scoped to the permissions of the token used to connect:

创建新的管理员令牌（请参阅管理员令牌功能页面上的创建管理员令牌）。
复制令牌值。在配置 AI 客户端时你将需要它。

令牌的权限决定了哪些 MCP 工具对 AI 客户端可见。例如，如果令牌仅在 Article 内容类型上授予 read，AI 客户端将只看到文章的列出和阅读工具。

🌐 The token's permissions determine which MCP tools are exposed to the AI client. For instance, if the token only grants read on an Article content-type, the AI client will only see listing and reading tools for articles.

AI客户端配置

🌐 AI client configuration

一旦你通过服务器配置文件启用了 MCP 服务器，并在管理面板中创建了管理员令牌，就将你的 AI 客户端连接到 Strapi MCP 服务器。

🌐 Once you have enabled the MCP server through the server configuration file and created an Admin token in the admin panel, connect your AI client to the Strapi MCP server.

Note

http://localhost:1337/ 在本页面的配置示例中使用。如果你的 Strapi 服务器托管在其他网址或端口，请相应地更新代码。

连接 Claude 桌面

🌐 Connecting Claude Desktop

打开 Claude Desktop 的配置文件。位置因你的系统而异：

🌐 Open Claude Desktop's configuration file. The location varies depending on your system:

操作系统	文件位置
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Tip

你也可以从 Claude 的设置中打开 Claude Desktop 的配置文件：进入设置 > 桌面应用 > 开发者，然后点击 编辑配置 按钮。

🌐 You can also open the configuration file for Claude Desktop from Claude's settings: go to Settings > Desktop app > Developer, then click on the Edit config button.

将 Strapi MCP 服务器添加到 Claude 的配置文件中，如下例所示，将 YOUR_ADMIN_TOKEN 替换为从 Strapi 管理面板配置中复制的管理员令牌值：

🌐 Add the Strapi MCP server to Claude's configuration file, as in the following example, replacing YOUR_ADMIN_TOKEN with the Admin token value copied from the Strapi admin panel configuration:

claude_desktop_config.json
{
  "mcpServers": {
    "strapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:1337/mcp",
        "--header",
        "Authorization: Bearer YOUR_ADMIN_TOKEN"
      ]
    }
  }
}

重启 Claude 桌面以使更改生效。

🌐 Restart Claude Desktop for the changes to take effect.

连接Claude代码

🌐 Connecting Claude Code

运行以下命令，将 YOUR_ADMIN_TOKEN 替换为从 Strapi 管理面板配置复制的管理员令牌值：

🌐 Run the following command, replacing YOUR_ADMIN_TOKEN with the Admin token value copied from the Strapi admin panel configuration:

terminal
claude mcp add strapi-mcp --transport http http://localhost:1337/mcp -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

连接 Codex

🌐 Connecting Codex

运行以下命令，将 YOUR_ADMIN_TOKEN 替换为保存从 Strapi 管理面板配置复制的管理员令牌值的环境变量名称：

🌐 Run the following command, replacing YOUR_ADMIN_TOKEN with the name of the environment variable holding the Admin token value copied from the Strapi admin panel configuration:

terminal
codex mcp add strapi-mcp --url http://localhost:1337/mcp --bearer-token-env-var YOUR_ADMIN_TOKEN

然后，在启动 codex 之前设置环境变量，或者把它加到你的 shell 里。运行 /mcp 来确认 strapi-mcp 显示为已连接。

🌐 Then, set the environment variable before launching codex or add it to your shell. Run /mcp to confirm strapi-mcp reports as connected.

连接光标

🌐 Connecting Cursor

将服务器添加到你的 .cursor/mcp.json 文件中：

🌐 Add the server to your .cursor/mcp.json file:

.cursor/mcp.json
{
  "mcpServers": {
    "strapi-mcp": {
      "type": "streamable-http",
      "url": "http://localhost:1337/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADMIN_TOKEN"
      }
    }
  }
}

连接帆板

🌐 Connecting Windsurf

将服务器添加到你的 ~/.codeium/windsurf/mcp_config.json 文件中：

🌐 Add the server to your ~/.codeium/windsurf/mcp_config.json file:

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

连接其他MCP客户端

🌐 Connecting other MCP clients

任何支持 MCP 可流式 HTTP 传输的客户端都可以连接。通用配置如下：

🌐 Any client that supports the MCP Streamable HTTP transport can connect. The generic configuration is as follows:

设置	值
传输类型	`streamable-http`
URL	`http://localhost:1337/mcp`（将主机和端口调整为你的 Strapi 实例）
授权头	`Bearer YOUR_ADMIN_TOKEN`

使用

🌐 Usage

MCP 服务器使用可流式的 HTTP 传输协议。任何兼容 MCP 的客户端都可以通过在 Authorization 头中使用 Bearer 令牌并指向 /mcp 端点来进行连接。一旦连接，AI 客户端可以使用自然语言提示与你的 Strapi 内容进行交互。

🌐 The MCP server uses the Streamable HTTP transport protocol. Any MCP-compatible client can connect by pointing to the /mcp endpoint with a Bearer token in the Authorization header. Once connected, the AI client can interact with your Strapi content using natural language prompts.

可用工具

🌐 Available tools

MCP 服务器提供三类工具：根据你的架构生成的内容管理工具、媒体库工具和内置的实用工具。

🌐 The MCP server exposes 3 categories of tools: content management tools generated from your schema, Media Library tools, and built-in utility tools.

内容管理工具

🌐 Content management tools

生成的工具取决于内容类型是集合类型还是单一类型。

🌐 The tools generated differ depending on whether the content type is a collection type or a single type.

集合类型 可生成最多 8 个工具：5 个用于 CRUD 操作，3 个用于草稿与发布操作：

工具	操作	所需权限	描述
`list`	读取	`read`	列出条目，支持分页、排序和筛选
`get`	读取	`read`	按文档 ID 获取单个条目
`create`	创建	`create`	创建新条目（如果启用了草稿和发布，则创建为草稿）
`update`	更新	`update`	按文档 ID 更新现有条目
`delete`	删除	`delete`	按文档 ID 删除条目
`publish`	发布	`publish`	发布草稿条目
`unpublish`	取消发布	`publish`	取消发布已发布条目
`discard_draft`	放弃草稿	`publish`	放弃草稿更改并恢复到已发布版本

单一类型 最多生成 6 个工具。由于单一类型总是表示恰好一个文档，因此没有 list 工具，并且创建/更新已合并为单个 write 工具：

工具	操作	所需权限	描述
`get`	读取	`read`	获取单类型文档
`write`	创建或更新	`create` 和/或 `update`	如果不存在文档，则创建文档；否则更新现有草稿
`delete`	删除	`delete`	删除单类型文档
`publish`	发布	`publish`	发布文档
`unpublish`	取消发布	`publish`	取消已发布文档的发布
`discard_draft`	丢弃草稿	`publish`	丢弃草稿更改并恢复到已发布版本

仅当内容类型上启用了 Draft & Publish 时，才会生成发布、取消发布和放弃草稿工具。

🌐 The publish, unpublish, and discard_draft tools are only generated when Draft & Publish is enabled on the content type.

媒体库工具

🌐 Media Library tools

5.54.0

Strapi 为 Media Library 注册了 10 个工具：3 个用于读取，7 个用于写入。与内容管理工具不同，它们不是从你的模式生成的，所以总是注册同一组工具。只有当管理员令牌授予以下列出的权限时，每个工具才会显示：令牌无法使用的工具不会出现在 tools/list 中，调用它会返回权限错误。

🌐 Strapi registers 10 tools for the Media Library: 3 for reading and 7 for writing. Unlike content management tools they are not generated from your schema, so the same set is always registered. Each tool is exposed only if the Admin token grants the permission listed below: a tool the token cannot use does not appear in tools/list, and calling it returns a permission error.

工具	所需权限	描述
`media_list_assets`	`plugin::upload.read`	列出资源，支持分页和可选过滤
`media_get_asset`	`plugin::upload.read`	通过其数字 `id` 返回单个资源
`media_list_folders`	`plugin::upload.read`	返回完整的文件夹树作为嵌套结构
`media_update_asset`	`plugin::upload.assets.update`	更新 `name`、`alternativeText` 或 `caption`
`media_move_assets`	`plugin::upload.assets.update`	批量将资源移动到另一个文件夹
`media_delete_assets`	`plugin::upload.assets.update`	批量永久删除资源
`media_create_folder`	`plugin::upload.assets.create`	创建一个文件夹，可选择放在父文件夹内
`media_rename_folder`	`plugin::upload.assets.update`	重命名文件夹
`media_move_folder`	`plugin::upload.assets.update`	将一个文件夹移动到另一个父文件夹中
`media_delete_folder`	`plugin::upload.assets.update`	删除文件夹及其所有内容

工具的响应包含一个固定的允许字段列表：id、name、alternativeText、caption、url、mime、size、width、height、ext、folder，以及时间戳。可能泄露存储提供商凭证或内部路径的字段（provider、provider_metadata、hash、formats、folderPath）不会被返回，即使以后内容类型有所扩展。

🌐 Tool responses include a fixed allowlist of fields: id, name, alternativeText, caption, url, mime, size, width, height, ext, folder, and timestamps. Fields that could expose storage provider credentials or internal paths (provider, provider_metadata, hash, formats, folderPath) are never returned, even if the content type is extended later.

资源和文件夹是用数字ID而不是文档ID来识别的，而且两者是独立的序列：同一个数字可以同时用来命名资源和文件夹。资源ID来自 media_list_assets 或 media_get_asset，文件夹ID来自 media_list_folders。

🌐 Assets and folders are identified by numeric ids rather than document IDs, and the two are independent sequences: the same number can name both an asset and a folder. Take asset ids from media_list_assets or media_get_asset, and folder ids from media_list_folders.

阅读。 media_list_assets 工具接受以下可选参数：

参数	类型	描述
`page`	数字	页码，从1开始（默认：1）。
`pageSize`	数字	每页资源数量（默认：25，最大：100）。
`folderId`	数字或 null	指定文件夹的数字ID，以列出该文件夹的资源，或者 `null` 仅列出根目录级别的资源。省略则列出所有文件夹的资源。
`mime`	字符串	MIME 类型过滤器。没有斜杠的值按前缀匹配（`"image"` 匹配所有 `image/*` 类型），完整类型则精确匹配，大小写不敏感（`"image/png"`）。
`name`	字符串	部分资源名称筛选（不区分大小写的子字符串匹配）。
`sort`	字符串	排序顺序（默认：`createdAt:DESC`）。只接受6个值：`createdAt:ASC`、`createdAt:DESC`、`name:ASC`、`name:DESC`、`updatedAt:ASC` 和 `updatedAt:DESC`。方向必须大写，其他值会被拒绝。

media_get_asset 工具需要 1 个参数：id，即数字资源 ID。不接受文档 ID 字符串。media_list_folders 工具不接受任何参数，并返回完整的文件夹层级。

🌐 The media_get_asset tool requires 1 parameter: id, the numeric asset ID. Document ID strings are not accepted. The media_list_folders tool accepts no parameters and returns the full folder hierarchy.

写作。 media_update_asset 只写入元数据。文件本身、它的 URL、MIME 类型和大小属于上传提供商，不能通过 MCP 修改。使用 media_move_assets 更改资源所在的文件夹，修改文件夹名称时使用 media_rename_folder 而不是 media_move_folder。

media_move_assets 和 media_move_folder 都可以将 null 作为目标，也就是媒体库的根目录。文件夹不能移动到自己里面或自己的子文件夹里。

Deletions are permanent

media_delete_assets 和 media_delete_folder 会从数据库和存储提供商中删除文件，以及所有生成的缩略图和尺寸变体。没有回收站，也不能撤销操作，删除文件夹会连带删除其中的所有子文件夹和文件。两个工具都无法判断某个资源是否被条目引用，所以删除成功并不意味着没有人正在使用它。

两者都接受一个 dryRun 参数，它会报告会被删除的内容，但不会实际删除任何东西。它们在部分失败的处理上不同：media_delete_assets 会保留成功删除的部分，并报告剩下的，而 media_delete_folder 如果有任何 ID 无法解析为文件夹，则会拒绝整个调用。

🌐 Both accept a dryRun parameter, which reports what would be removed without removing anything. They differ on partial failure: media_delete_assets keeps the deletions that succeeded and reports the rest, while media_delete_folder rejects the whole call if any id does not resolve to a folder.

内置实用工具

🌐 Built-in utility tools

除了内容管理工具之外，Strapi 还注册了以下内置工具：

🌐 In addition to content management tools, Strapi registers the following built-in tools:

工具	可用性	描述
`log`	仅开发模式	在指定级别 (`info`, `warn`, `error`, `http`, `log`) 下将消息记录到 Strapi 服务器控制台。对调试 MCP 交互很有用。

内置的实用工具仅在开发模式下可用（当启用 autoReload 时），且不需要特定的管理员权限。

🌐 Built-in utility tools are only available in development mode (when autoReload is enabled) and do not require specific admin permissions.

通过提示进行内容管理

🌐 Content management through prompts

一旦连接，你就可以使用自然语言与你的 Strapi 内容进行交互：

🌐 Once connected, you can interact with your Strapi content using natural language:

提示	会发生什么
"创建一个标题为 'Hello World'、正文为 'First post' 的新文章。"	创建一个草稿文章条目
"列出最近的 5 篇文章。"	返回分页列表，按最新排序
"显示 ID 为 abc123 的文章。"	返回完整条目
"更新文章 abc123，将标题改为 'Hello Strapi'。"	更新标题，其他字段不变
"发布文章 abc123。"	将条目状态更改为已发布
"删除文章 abc123。"	删除该条目
"用法语创建一篇标题为 'Bonjour le monde' 的文章。"	创建一个草稿文章，并将 `locale` 设置为 `fr`

国际化 (i18n)

🌐 Internationalization (i18n)

当在内容类型上启用国际化 (i18n)时，MCP 工具接受一个可选的 locale 参数（例如，"en"、"fr"）。如果省略，则使用默认语言环境。

🌐 When Internationalization (i18n) is enabled on a content type, MCP tools accept an optional locale parameter (e.g., "en", "fr"). If omitted, the default locale is used.

AI 客户端可以查看每个工具架构中可用的语言环境，因此你可以要求它以特定语言创建或更新内容。例如，询问“用法语创建一篇标题为 'Bonjour' 的文章”会将 locale: "fr" 传递给 create 工具。可用的语言环境取决于管理员令牌的权限（请参见权限边界）。

🌐 The AI client sees which locales are available in each tool's schema, so you can ask it to create or update content in a specific language. For example, asking "Create an article in French titled 'Bonjour'" passes locale: "fr" to the create tool. Which locales are available depends on the Admin token's permissions (see Permission boundaries).

Tip

在处理本地化内容时，请在提示中明确提及目标语言，以便 AI 客户端传递正确的 locale 值。例如，建议使用“创建一篇法语文章”，而不是“创建一篇标题为‘Bonjour’的文章”，以避免歧义。

🌐 When working with localized content, explicitly mention the target language in your prompt so the AI client passes the correct locale value. For instance, prefer "Create an article in French" over "Create an article titled 'Bonjour'" to avoid ambiguity.

排序

🌐 Sorting

list 工具接受一个 sort 参数，该参数支持 4 种表示法：

🌐 The list tool accepts a sort parameter that supports 4 notations:

符号	示例
字符串	`"title:asc"`
字符串数组	`["title:asc", "createdAt:desc"]`
对象	`{ "title": "asc" }`
对象数组	`[{ "title": "asc" }, { "createdAt": "desc" }]`

排序字段名称仅限于内容类型的标量属性（字符串、数字、布尔值、日期、枚举）。关系、组件、动态区、媒体和 JSON 字段无法进行排序。

🌐 Sort field names are constrained to the content type's scalar attributes (strings, numbers, booleans, dates, enumerations). Relation, component, dynamic zone, media, and JSON fields cannot be sorted on.

过滤

🌐 Filtering

list 工具使用 Strapi 的过滤语法接受 filters 参数：

🌐 The list tool accepts a filters parameter using Strapi's filter syntax:

字段运算符：$eq、$ne、$in、$notIn、$lt、$lte、$gt、$gte、$between、$contains、$notContains、$startsWith、$endsWith、$null、$notNull，以及它们的不区分大小写变体（$eqi、$nei、$containsi、$notContainsi、$startsWithi、$endsWithi）。
逻辑运算符：$and、$or（接受过滤器对象数组）、$not（封装单个过滤器对象）。
隐式相等：直接传递一个值（例如，{ "title": "Hello" }）等同于 { "title": { "$eq": "Hello" } }。

像排序字段一样，筛选字段也仅限于标量属性。

🌐 Like sort fields, filter fields are constrained to scalar attributes only.

分页

🌐 Pagination

list 工具也接受 page（从 1 开始索引，默认值：1）和 pageSize（默认值：25，最大值：100）参数。

🌐 The list tool also accepts page (1-indexed, default: 1) and pageSize (default: 25, max: 100) parameters.

关系

🌐 Relations

关联字段既支持简写的文档 ID 字符串，也支持完整的关联对象。

🌐 Relation fields support both a shorthand document ID string and a full relation object.

一对一关系 (oneToOne, manyToOne) 接受：

一个文档 ID 字符串："z7v8zma53x01r6oceimv922b"
一个关系对象：{ "documentId": "z7v8zma53x01r6oceimv922b", "locale": "en", "status": "draft" }（locale 和 status 可选）
null 清除关系

多对多关系 (oneToMany, manyToMany) 接受一个包含以下一个或多个键的关系对象：

键	描述
`connect`	添加关系。接受文档 ID 字符串数组或 `{ documentId, locale?, status?, position? }` 对象。可选的 `position` 键支持 `{ before?, after?, start?, end? }` 排序提示（默认: `{ end: true }`）。
`disconnect`	移除关系。接受文档 ID 字符串数组或 `{ documentId, locale?, status? }` 对象。
`set`	使用提供的数组替换所有现有关系。传递 `null` 可清除所有关系。与 `connect`/`disconnect` 互斥。

权限边界

🌐 Permission boundaries

MCP 服务器执行与 Strapi 管理面板相同的权限模型。权限会在多个层级进行检查：

🌐 The MCP server enforces the same permission model as the Strapi admin panel. Permissions are checked at multiple levels:

工具可见性：当 AI 客户端连接时，Strapi 会检查管理员令牌的权限，并且只显示令牌有权限访问的工具。如果令牌未授予在 Article 上的 delete，AI 客户端将完全看不到用于文章的删除工具。
字段过滤：即使在公开的工具中，输入和输出模式也仅限于令牌可以访问的字段。如果令牌在 Article 上授予 read 权限，但排除了 body 字段，则 AI 客户端将无法看到或接收 body 内容。字段限制是针对每个操作独立应用的。写入模式（create、update）仅包括对应操作允许的字段。
区域过滤：当启用国际化 (i18n)功能并配置了区域级权限时，locale参数会根据每个操作进行限制。例如，某个令牌可能允许读取en和fr的内容，但只允许在en中创建内容。如果默认区域被允许用于给定操作，则该区域会作为 Zod 模式的默认值应用，因此 AI 客户端无需显式指定区域。
运行时执行：除了模式级别的限制外，每个处理程序在运行时都会调用 Strapi 的权限检查器，以验证对正在读取、写入或发布的特定文档的访问。基于条件的权限（例如，“仅更新你拥有的条目”）在此级别执行。

这意味着你可以创建具有细粒度访问权限的令牌：

🌐 This means you can create tokens with fine-grained access:

一个只提供列表和读取工具的“只读”令牌
一个限定于特定内容类型的令牌（例如，仅限文章而不包括分类）
一个仅限于特定字段或区域的令牌
具有基于条件权限的令牌（例如，仅更新自己拥有的条目）

Tip

为每个 AI 客户端或用例创建专用的管理员令牌。使用仍然允许 AI 完成其任务的最严格权限。

🌐 Create dedicated Admin tokens for each AI client or use case. Use the most restrictive permissions that still allow the AI to accomplish its task.

审计日志

🌐 Audit logs

Enterprise 5.52.0

通过 MCP 服务器执行的入口操作会记录在审计日志中。每个日志数据包都会带有一个 origin 键，其值为 mcp，用于区分由 AI 客户端触发的操作和在管理面板中执行的操作。仅读取内容的操作不会被记录。

🌐 Entry actions performed through the MCP server are recorded in the Audit Logs. Each log payload carries an origin key set to mcp, which distinguishes actions triggered by an AI client from actions performed in the admin panel. Operations that only read content are not recorded.

无状态架构

🌐 Stateless architecture

MCP 服务器使用无状态架构。每个对 /mcp 端点的 POST 请求都会创建一个新的、短暂的 MCP 服务器实例，该实例的作用范围由已认证令牌的权限决定。请求之间没有会话持久性：每个请求都是独立进行身份验证和授权的。由于没有会话状态，AI 客户端无需管理会话 ID，并且权限更改（例如撤销令牌或更新其权限）会在下一次请求中生效。

🌐 The MCP server uses a stateless architecture. Each POST request to the /mcp endpoint creates a fresh, ephemeral MCP server instance scoped to the authenticated token's permissions. There is no session persistence between requests: every request is independently authenticated and authorized. Because there is no session state, the AI client does not need to manage session IDs, and permission changes (such as revoking a token or updating its permissions) take effect on the next request.

/mcp 端点上的 GET 和 DELETE HTTP 方法会返回 405 Method Not Allowed JSON-RPC 错误，因为 MCP 服务器仅接受 POST 请求。

🌐 GET and DELETE HTTP methods on the /mcp endpoint return a 405 Method Not Allowed JSON-RPC error, as the MCP server only accepts POST requests.

已知限制

🌐 Known limitations

MCP 服务器有以下限制：

🌐 The MCP server has the following limitations:

动态区域：动态区域字段在工具模式中以无类型数组的形式传递。动态区域中每个组件的内部结构未被描述。
嵌套人口参数：list 和 get 工具不支持关系的嵌套人口参数。
媒体上传：媒体字段接受现有的媒体资源引用，但 MCP 服务器无法上传新文件。请先使用 Strapi 的媒体库或上传 API 添加文件，然后在 MCP 工具调用中引用它们。
自定义字段：通过插件注册的自定义字段会映射到其底层的 Strapi 类型。如果在注册 MCP 工具时自定义字段注册表未被填充，该自定义字段将回退到 unknown 类型。
循环组件引用：直接或间接引用自身的组件，在循环点将回退到一个开放的 record<string, unknown> 模式，而不是形成无限递归结构。

兼容性和模式更改

🌐 Compatibility and schema changes

从上面提到的版本开始，内置的 MCP 服务器使用的是 MCP TypeScript SDK v2。这带来了两个会影响客户端和功能作者的变化。

🌐 Starting with the version noted above, the built-in MCP server uses MCP TypeScript SDK v2. This brings two changes that affect clients and capability authors.

JSON 架构 2020-12

🌐 JSON Schema 2020-12

工具 inputSchema 和 outputSchema 的文档现在序列化为 JSON Schema 2020-12，而不是早期版本使用的 draft-07 方言。主要的格式差异如下：

🌐 Tool inputSchema and outputSchema documents are now serialized as JSON Schema 2020-12 instead of the draft-07 dialect used in earlier versions. The key formatting differences are:

位置元组使用 prefixItems 而不是 draft-07 的 items 数组形式。
递归模式（包括内容类型的 list_* 过滤参数）通过 $defs 引用共享定义，而不是 definitions。

一个严格的 MCP 客户端，现在可以根据 JSON Schema 2020-12 验证广告的模式，并保留 Strapi 广告的每个工具。在此更改之前，这些客户端会拒绝 draft-07 模式，并默默地从可用工具列表中删除工具，这看起来像是权限缺失的问题，但服务器端没有记录错误。这就是 strapi/strapi#27395 中描述的失败情况。完全不验证模式方言的客户端则不会受到影响。

🌐 A strict MCP client that validates advertised schemas against JSON Schema 2020-12 now retains every tool Strapi advertises. Before this change, those clients rejected the draft-07 schemas and silently dropped tools from the usable list, which appeared as a missing-permissions problem with no server-side error logged. This is the failure described in strapi/strapi#27395. Clients that do not validate the schema dialect at all are not affected.

处理器上下文和能力结果类型

🌐 Handler context and capability result types

功能处理程序仍然会接收到 { args, extra }。extra 值现在是 Strapi 拥有的、全可选的处理程序上下文。你在功能处理程序中已经使用的字段名称保持不变：取消、请求和会话身份、令牌信息、请求元数据，以及来源 HTTP 请求的详细信息。

🌐 Capability handlers still receive { args, extra }. The extra value is now a Strapi-owned, all-optional handler context. The field names you already use in capability handlers are unchanged: cancellation, request and session identity, token information, request metadata, and originating HTTP request details.

工具、提示和资源结果是 Strapi 拥有的类型，从 @strapi/types (McpToolResult、McpPromptResult、McpResourceReadResult、McpResourceListingMetadata、McpContentBlock) 导出。现有的结构仍然有效，包括所有五种内容变体、资源文本和二进制内容，以及扩展字段。@strapi/types 不再直接依赖 MCP SDK；核心部分保留 SDK 依赖只是用于传输。

🌐 Tool, prompt, and resource results are Strapi-owned types exported from @strapi/types (McpToolResult, McpPromptResult, McpResourceReadResult, McpResourceListingMetadata, McpContentBlock). Existing constructions remain valid, including all five content variants, resource text and blob contents, and extension fields. @strapi/types no longer depends on the MCP SDK directly; core retains the SDK dependency for transport only.

现在空的能力类别会列为一个空列表，而不是返回未知方法错误。

🌐 Empty capability categories now enumerate as an empty list instead of returning an unknown-method error.

插件 API

🌐 Plugin API

Strapi 插件可以通过 strapi.ai.mcp 服务注册额外的 MCP 工具，因此 AI 客户端可以触发特定插件的操作。点击下面的卡片以阅读更多详情：

🌐 Strapi plugins can register additional MCP tools through the strapi.ai.mcp service, so AI clients can trigger plugin-specific actions. Click on the card below to read more details:

扩展 MCP 服务器

通过 strapi.ai.mcp 服务从 Strapi 插件注册自定义 MCP 工具。

配置​

基于代码的 Strapi 配置​

高级选项​

Strapi 管理面板配置​

AI客户端配置​

连接 Claude 桌面​

连接Claude代码​

连接 Codex​

连接光标​

连接帆板​

连接其他MCP客户端​

使用​

可用工具​

内容管理工具​

媒体库工具​

内置实用工具​

通过提示进行内容管理​

国际化 (i18n)​

排序​

过滤​

分页​

关系​

权限边界​

审计日志​

无状态架构​

已知限制​

兼容性和模式更改​

JSON 架构 2020-12​

处理器上下文和能力结果类型​

插件 API​