diff --git a/.gitignore b/.gitignore index 4c5f2067e3..e099ae5f53 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ .claude/ +.superpowers/ +docs/superpowers/ diff --git a/agents/prompts/style-checker.md b/agents/prompts/style-checker.md index 211377e154..fec3a22089 100644 --- a/agents/prompts/style-checker.md +++ b/agents/prompts/style-checker.md @@ -209,6 +209,10 @@ Beyond the 12 rules, also check for: - In TabItems: `value` must be lowercase (`yarn`, `npm`), `label` must be `Yarn` or `NPM` - Do NOT flag these as inconsistencies when used correctly per context. +### Strapi terminology +- **Detect:** Internationalization (i18n) referred to as a "plugin" instead of a "feature". Since Strapi 5, i18n is a core feature, not a plugin. Also watch for other core features (Upload, Content Manager, Content-Type Builder) being called "plugins". +- **Severity:** warning + ### Cross-reference formatting - **Detect:** Standalone "See [link]." sentences that could be integrated as parentheticals into the preceding sentence (e.g., "Configure X. See [Y]." → "Configure X (see [Y]).") - **Severity:** warning diff --git a/docusaurus/docs/cms/ai/docs-mcp-server.md b/docusaurus/docs/cms/ai/docs-mcp-server.md new file mode 100644 index 0000000000..4afd87ef1c --- /dev/null +++ b/docusaurus/docs/cms/ai/docs-mcp-server.md @@ -0,0 +1,113 @@ +--- +title: Docs MCP server +description: Connect an MCP server for the Strapi documentation to your IDE for Strapi-aware code suggestions and answers. +sidebar_label: Docs MCP server +displayed_sidebar: cmsSidebar +tags: + - ai + - MCP + - developer tools +toc_max_heading_level: 3 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Docs MCP server + + + +A Docs MCP server exposes the Strapi documentation to AI coding tools. Connect it to your IDE to get Strapi-aware code suggestions and answers directly in your development environment. + + + +The Docs [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server is powered by [Kapa](https://kapa.ai), the same service behind the **Ask AI** button on the documentation website. It draws from the full Strapi documentation, including guides, API references, and code examples. The Docs MCP server is part of the [AI tools for developers](/cms/ai/for-developers) that Strapi offers. + +:::strapi MCP servers for Strapi +Strapi offers 2 different MCP servers: + +- the Docs MCP server, covered on the present page, +- and the Strapi MCP server for content management, covered on its [dedicated feature page](/cms/features/strapi-mcp-server). +::: + +## Compatible tools + +The MCP server works with any tool that supports the MCP protocol, including: + +- [Cursor](https://cursor.com) +- [VS Code](https://code.visualstudio.com) with GitHub Copilot +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) +- [Windsurf](https://codeium.com/windsurf) +- Any other MCP-compatible IDE or tool + +## Connection details + +When opening the Ask AI window, you should see a **Use MCP** dropdown in the top right corner. Click on it and choose which tool you'd like to connect: + + + +If manual MCP server configuration is required: + +1. Click the **Copy MCP URL** from the dropdown. The server URL should be: `https://strapi-docs.mcp.kapa.ai` +2. Add the server to your IDE's MCP configuration file: + + + + + Add to your `.cursor/mcp.json` file: + + ```json title=".cursor/mcp.json" + { + "mcpServers": { + "strapi-docs": { + "url": "https://strapi-docs.mcp.kapa.ai" + } + } + } + ``` + + + + + Add to your `.vscode/mcp.json` file: + + ```json title=".vscode/mcp.json" + { + "servers": { + "strapi-docs": { + "type": "http", + "url": "https://strapi-docs.mcp.kapa.ai" + } + } + } + ``` + + + + + Add to your `~/.codeium/windsurf/mcp_config.json` file: + + ```json title="~/.codeium/windsurf/mcp_config.json" + { + "mcpServers": { + "strapi-docs": { + "serverUrl": "https://strapi-docs.mcp.kapa.ai" + } + } + } + ``` + + + + +Once connected, your AI coding assistant can query the Strapi documentation directly to answer questions, suggest implementations, and verify API usage. + +:::tip +For docs-related questions, start your prompts with `Use the strapi-docs MCP server to answer:`. This will ensure the tool queries docs.strapi.io instead of returning answers based on its training data, which can be outdated. +::: diff --git a/docusaurus/docs/cms/ai/for-content-managers.md b/docusaurus/docs/cms/ai/for-content-managers.md index 8869f65d23..48481ca07d 100644 --- a/docusaurus/docs/cms/ai/for-content-managers.md +++ b/docusaurus/docs/cms/ai/for-content-managers.md @@ -1,11 +1,12 @@ --- -title: Strapi AI for content managers -description: Learn about AI-powered features in the Strapi admin panel, such as content-type design, automatic translations, and media metadata generation. +title: AI for content managers +description: Learn about AI-powered features in the Strapi admin panel and the built-in MCP server that lets AI clients manage your content. sidebar_label: AI for content managers displayed_sidebar: cmsSidebar tags: - ai - features +- MCP - Content-Type Builder - Internationalization (i18n) - Media Library @@ -15,13 +16,17 @@ toc_max_heading_level: 3 import StrapiAiCredits from '/docs/snippets/strapi-ai-credits.md' -# Strapi AI for content management +# AI for content managers + +This page covers the AI-powered capabilities available to content managers in Strapi: the Strapi AI features built into the admin panel, and the MCP server that lets AI clients manage your content. + +## Strapi AI Some Strapi CMS features can be enhanced with Strapi AI, helping content managers and administrators design content structures, translate content automatically, and generate asset metadata, all from the admin panel. -## Activation and configuration {#activation} +### Activation and configuration {#activation} Strapi AI is available for Growth plan users since Strapi 5.30 and works with both Strapi Cloud and self-hosted deployments. To get started: @@ -42,14 +47,15 @@ module.exports = { See [Admin panel configuration > Strapi AI](/cms/configurations/admin-panel#strapi-ai) for all configuration options. -## Available features {#features} +### Available features {#features} | Feature | Description | |---------|-------------| | [Content-Type Builder](/cms/features/content-type-builder#strapi-ai) | AI chat assistant that helps design content-type structures, explain existing schemas, and plan data models. Uses your existing content types as context. | | [Internationalization](/cms/features/internationalization#ai-powered-internationalization) | Automatically translates content from the default locale to all other configured locales when you save an entry. | | [Media Library](/cms/features/media-library#ai-powered-metadata-generation) | Generates alternative text, captions, and descriptions for uploaded images. | -## Credits and data handling {#credits} + +### Credits and data handling {#credits} Strapi AI features consume AI credits. @@ -58,3 +64,9 @@ Strapi AI features consume AI credits. All AI requests are processed through Strapi-managed infrastructure. Content is only used temporarily during each request and is not stored outside your instance. Strapi AI follows the same GDPR-aligned framework as Strapi Cloud. See [Usage information > Strapi AI data handling](/cms/usage-information#strapi-ai-data-handling) for more details. + +## Strapi MCP server + +Strapi includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI clients like Claude, Cursor, or any MCP-compatible tool manage your content through natural language. Once enabled and connected, an AI client can create, read, update, delete, publish, and unpublish entries directly through Strapi's Content Manager, all gated by Admin token permissions. + + diff --git a/docusaurus/docs/cms/ai/for-developers.md b/docusaurus/docs/cms/ai/for-developers.md index 90354ae4e6..37d347bf78 100644 --- a/docusaurus/docs/cms/ai/for-developers.md +++ b/docusaurus/docs/cms/ai/for-developers.md @@ -104,77 +104,20 @@ This is particularly useful for understanding configuration examples, API respon - **`llms-full.txt`**: Use this when you need the AI to have access to the complete documentation content. This is a large file; make sure your model's context window can handle it. - **`llms-code.txt`**: Use this when you're working on code and want to give an AI all of Strapi's documented code examples. Each snippet includes the source page URL and anchor for traceability. -## Docs MCP server {#docs-mcp} +## MCP servers {#mcp} -A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the documentation is available. The Docs MCP server exposes the Strapi documentation to AI coding tools. Connect it to your IDE to get Strapi-aware code suggestions and answers directly in your development environment. +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI tools interact with external services. 2 MCP servers are available for Strapi: -### Compatible tools - -The MCP server works with any tool that supports the MCP protocol, including: - -- [Cursor](https://cursor.com) -- [VS Code](https://code.visualstudio.com) with GitHub Copilot -- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) -- [Windsurf](https://codeium.com/windsurf) -- Any other MCP-compatible IDE or tool - -### Connection details - -When opening the Ask AI window, you should see a **Use MCP** dropdown in the top right corner. Click on it and choose which tool you'd like to connect: - - - -If manual MCP server configuration is required: - -1. Click the **Copy MCP URL** from the dropdown. The server URL should be: `https://strapi-docs.mcp.kapa.ai` -2. Update the MCP server configuration in your IDE: - - - - - Add to your `.cursor/mcp.json` file: - - ```json title=".cursor/mcp.json" - { - "mcpServers": { - "strapi-docs": { - "url": "https://strapi-docs.mcp.kapa.ai" - } - } - } - ``` - - - - - Add to your `.vscode/mcp.json` file: - - ```json title=".vscode/mcp.json" - { - "servers": { - "strapi-docs": { - "type": "http", - "url": "https://strapi-docs.mcp.kapa.ai" - } - } - } - ``` - - - - -Once connected, your AI coding assistant can query the Strapi documentation directly to answer questions, suggest implementations, and verify API usage. + + + + ## Tips for better results {#tips} +The following tips will help you fine-tune your prompts to get the best results: +- Use the [Docs MCP server](/cms/ai/docs-mcp-server) in your IDE for the fastest developer experience. For docs-related questions, prefix your prompt with `Use the strapi-docs MCP server to answer:` so the tool queries docs.strapi.io instead of using potentially outdated training data. - Include the page URL so the assistant grounds its answer in the right context. - Mention your Strapi version (e.g., Strapi 5) to avoid outdated suggestions. - Pair code examples with their source page when sharing snippets from `llms-code.txt`. - Prefer documented APIs over private internals when asking for code generation. -- Use the MCP server in your IDE for the fastest developer experience. diff --git a/docusaurus/docs/cms/configurations/features.md b/docusaurus/docs/cms/configurations/features.md index 9fc6f0c355..52c43ff21b 100644 --- a/docusaurus/docs/cms/configurations/features.md +++ b/docusaurus/docs/cms/configurations/features.md @@ -35,16 +35,16 @@ To enable a future flag: 1. (_optional_) If the server is running, stop it with `Ctrl-C`. 2. Open the `config/features.js|ts` file or create it if the file does not exist yet. The file will export a `future` object with all the future flags to enable. -3. To enable a future flag, add its property name (see [full list](#available-future-flags)) to the `future` object and ensure the property's value is set to `true`. The following example shows how to enable the `adminTokens` future flag: +3. To enable a future flag, add its property name (see [full list](#available-future-flags)) to the `future` object and ensure the property's value is set to `true`. The following example shows how to enable the `experimental_firstPublishedAt` future flag: - ```ts title="/config/features.ts" + ```js title="/config/features.js" module.exports = ({ env }) => ({ future: { - adminTokens: env.bool('STRAPI_FUTURE_ADMIN_TOKENS', false), + experimental_firstPublishedAt: env.bool('STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT', false), }, }) @@ -53,27 +53,27 @@ To enable a future flag: This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line: ```json title=".env" - STRAPI_FUTURE_ADMIN_TOKENS=true + STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT=true ``` - If your environment file does not include this value, the `adminTokens` future flag property value will default to `false` and the experimental feature will not be enabled. + If your environment file does not include this value, the `experimental_firstPublishedAt` future flag property value will default to `false` and the experimental feature will not be enabled. ```ts title="/config/features.ts" - export default { + export default ({ env }) => ({ future: { - adminTokens: env.bool('STRAPI_FUTURE_ADMIN_TOKENS', false), + experimental_firstPublishedAt: env.bool('STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT', false), }, - }; + }); ``` This example assumes that you have an `.env` environment file at the root of your application and that the file includes the following line: ```json title=".env" - STRAPI_FUTURE_ADMIN_TOKENS=true + STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT=true ``` If your environment file does not include this value, the `experimental_firstPublishedAt` future flag property value will default to `false` and the experimental feature will not be enabled. @@ -112,5 +112,4 @@ Developers can use the following APIs to interact with future flags: | Property name | Related feature | Suggested environment variable name | | ------------- | --------------- | ---------------------------------- | | `experimental_firstPublishedAt` | [Draft & Publish](/cms/features/draft-and-publish#recording-the-first-publication-date) | `STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT` | -| `adminTokens` | [Admin Tokens](/cms/features/admin-tokens) | `STRAPI_FUTURE_ADMIN_TOKENS` | diff --git a/docusaurus/docs/cms/faq.md b/docusaurus/docs/cms/faq.md index 3aaab60456..f8465ae0e2 100644 --- a/docusaurus/docs/cms/faq.md +++ b/docusaurus/docs/cms/faq.md @@ -23,7 +23,7 @@ tags: --- -# Frequently Asked Questions +# Frequently asked questions Below are answers and solutions to most common issues that you may experience when working with Strapi. @@ -152,5 +152,6 @@ You can see the ) server is in [development](https://github.com/strapi/strapi/discussions/25398) and will be available soon. -Meanwhile, a different [MCP server for Strapi Docs](https://docs.strapi.io/cms/ai/for-developers#docs-mcp) is already available. +Yes. Strapi includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes content management tools to AI clients. See the [MCP server feature page](/cms/features/strapi-mcp-server) for configuration and usage details. + +A separate [Docs MCP server](/cms/ai/docs-mcp-server) is also available for querying the Strapi documentation. diff --git a/docusaurus/docs/cms/features/admin-tokens.md b/docusaurus/docs/cms/features/admin-tokens.md index cd2bc32496..392b773b43 100644 --- a/docusaurus/docs/cms/features/admin-tokens.md +++ b/docusaurus/docs/cms/features/admin-tokens.md @@ -1,5 +1,5 @@ --- -title: Admin Tokens +title: Admin tokens description: Learn how to use Admin tokens to authenticate programmatic access to the Strapi Admin API. toc_max_heading_level: 4 displayed_sidebar: cmsSidebar @@ -11,8 +11,7 @@ tags: - features --- -# Admin Tokens - +# Admin tokens Admin tokens authenticate programmatic access to the Strapi Admin API. Each token is scoped to a subset of its owner's permissions and is designed for automation workflows such as MCP agents, CI/CD pipelines, and scripts. @@ -30,7 +29,7 @@ Admin tokens and API tokens are strictly separated: each is rejected on the othe Activated by default for Super Admin. Each lower-level role needs an explicit permission grant in Roles > Settings - Admin tokens. - Requires enabling the corresponding future flag,
see [Features configuration](/cms/configurations/features) + Available and activated by default Available in both Development & Production environment @@ -56,7 +55,7 @@ Admin tokens are configured entirely from the admin panel. No code-based configu :::prerequisites If you're not the Strapi instance's super admin, the super admin must have granted you the following permissions: * access the Admin tokens settings page - * create (generate) admin tokens + * create (generate) Admin tokens (see [RBAC > Configuring role's permissions](/cms/features/rbac#plugins-and-settings) for details). ::: @@ -78,7 +77,6 @@ If you're not the Strapi instance's super admin, the super admin must have grant ::: 4. Click on the **Save** button. The new Admin token will be displayed at the top of the interface, along with a copy button . - + + + +Strapi includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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. + + + +The MCP server exposes a set of content management tools to AI clients such as Claude Desktop, Claude Code, 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. + + + Free feature + Admin (token creator) + Server configuration + Available in both Development & Production environment + + +## Configuration + +Before first use, the Strapi MCP server must be: +- enabled through the server configuration file and authenticated with Admin tokens created in the admin panel +- connected to your AI client. + +### Strapi code-based configuration + +Enable the MCP server by adding the `mcp` object to the server configuration file: + + + + +```js title="config/server.js" +module.exports = ({ env }) => ({ + host: env('HOST', '0.0.0.0'), + port: env.int('PORT', 1337), + app: { + keys: env.array('APP_KEYS'), + }, + // highlight-start + mcp: { + enabled: true, + }, + // highlight-end +}); +``` + + + + +```ts title="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'), + }, + // highlight-start + mcp: { + enabled: true, + }, + // highlight-end +}); +export default config; +``` + + + + +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 + +The following optional keys can be added to the `mcp` configuration object: + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `enabled` | Boolean | `false` | Enable or disable the MCP server. | +| `connectTimeoutMs` | Number | `5000` | Maximum time (in ms) for the internal MCP transport to connect before the request is aborted. | +| `requestTimeoutMs` | Number | `60000` | Maximum time (in ms) for a single MCP request to complete before it times out. | + +```js title="config/server.js" +mcp: { + enabled: true, + connectTimeoutMs: 10000, // 10 seconds + requestTimeoutMs: 120000, // 2 minutes +}, +``` + + +### Strapi admin panel configuration + +The MCP server authenticates requests using Admin tokens. Each MCP session is scoped to the permissions of the token used to connect: + +1. Create a new Admin token (see [Creating an Admin token](/cms/features/admin-tokens#creating-a-new-admin-token) on the Admin tokens feature page). +2. Copy the token value. You will need it when configuring the AI client. + +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 client configuration + +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/` is used in configuration examples on this page. If your Strapi server is hosted on another URL or port, please update the code accordingly. +::: + +#### Connecting Claude Desktop + +Open Claude Desktop's configuration file. The location varies depending on your system: + +| OS | File location | +|----|---------------| +| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | +| Windows | `%APPDATA%\Claude\claude_desktop_config.json` | + +:::tip +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. +::: + +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](#strapi-admin-panel-configuration): + +```json title="claude_desktop_config.json" +{ + "mcpServers": { + "strapi-mcp": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "http://localhost:1337/mcp", + "--header", + "Authorization: Bearer YOUR_ADMIN_TOKEN" + ] + } + } +} +``` + +Restart Claude Desktop for the changes to take effect. + +#### Connecting Claude Code + +Run the following command, replacing `YOUR_ADMIN_TOKEN` with the Admin token value copied from the [Strapi admin panel configuration](#strapi-admin-panel-configuration): + +```bash +claude mcp add strapi-mcp --transport http http://localhost:1337/mcp -H "Authorization: Bearer YOUR_ADMIN_TOKEN" +``` + +Restart Claude Code, then run `/mcp` to confirm `strapi-mcp` reports as connected. + +#### Connecting Cursor + +Add the server to your `.cursor/mcp.json` file: + +```json title=".cursor/mcp.json" +{ + "mcpServers": { + "strapi-mcp": { + "type": "streamable-http", + "url": "http://localhost:1337/mcp", + "headers": { + "Authorization": "Bearer YOUR_ADMIN_TOKEN" + } + } + } +} +``` + +#### Connecting Windsurf + +Add the server to your `~/.codeium/windsurf/mcp_config.json` file: + +```json title="~/.codeium/windsurf/mcp_config.json" +{ + "mcpServers": { + "strapi-mcp": { + "serverUrl": "http://localhost:1337/mcp", + "headers": { + "Authorization": "Bearer YOUR_ADMIN_TOKEN" + } + } + } +} +``` + +#### Connecting other MCP clients + +Any client that supports the MCP Streamable HTTP transport can connect. The generic configuration is as follows: + +| Setting | Value | +|---------|-------| +| Transport type | `streamable-http` | +| URL | `http://localhost:1337/mcp` (adjust host and port to your Strapi instance) | +| Authorization header | `Bearer YOUR_ADMIN_TOKEN` | + +## Usage + +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 + +The MCP server exposes 2 categories of tools: content-type tools generated from your schema, and built-in utility tools. + +#### Content-type tools + +For each content type the token has access to, Strapi generates up to 8 tools: 5 for CRUD operations (list, get, create, update, delete) and 3 for [Draft & Publish](/cms/features/draft-and-publish) actions (publish, unpublish, discard draft): + +| Tool | Action | Permission required | Description | +|------|--------|-------------------|-------------| +| `list` | Read | `read` | List entries with pagination, sorting, and filtering | +| `get` | Read | `read` | Get a single entry by document ID | +| `create` | Create | `create` | Create a new entry (created as draft if Draft & Publish is enabled) | +| `update` | Update | `update` | Update an existing entry by document ID | +| `delete` | Delete | `delete` | Delete an entry by document ID | +| `publish` | Publish | `publish` | Publish a draft entry | +| `unpublish` | Unpublish | `publish` | Unpublish a published entry | +| `discard_draft` | Discard draft | `publish` | Discard draft changes and revert to the published version | + +The last 3 tools (publish, unpublish, discard_draft) are only generated for content types that have [Draft & Publish](/cms/features/draft-and-publish) enabled. + + +#### Built-in utility tools + +In addition to content-type tools, Strapi registers the following built-in tools: + +| Tool | Availability | Description | +|------|-------------|-------------| +| `log` | Development mode only | Logs a message to the Strapi server console at a specified level (`info`, `warn`, `error`, `http`, `log`). Useful for debugging MCP interactions. | + +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 + +Once connected, you can interact with your Strapi content using natural language: + +| Prompt | What happens | +|--------|-------------| +| "Create a new article titled 'Hello World' with body 'First post'." | Creates a draft article entry | +| "List the 5 most recent articles." | Returns paginated list, newest first | +| "Show me article with ID abc123." | Returns the full entry | +| "Update article abc123, change the title to 'Hello Strapi'." | Updates the title, other fields untouched | +| "Publish article abc123." | Changes the entry status to published | +| "Delete article abc123." | Removes the entry | +| "Create an article in French with the title 'Bonjour le monde'." | Creates a draft article with `locale` set to `fr` | + + +#### Internationalization (i18n) + +When [Internationalization (i18n)](/cms/features/internationalization) is enabled on a content type, MCP tools accept an optional `locale` parameter (e.g., `"en"`, `"fr"`). If omitted, the default locale is used. + +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](#permission-boundaries)). + +:::tip +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 + +The `list` tool accepts a `sort` parameter that supports 4 notations: + +| Notation | Example | +|----------|---------| +| String | `"title:asc"` | +| Array of strings | `["title:asc", "createdAt:desc"]` | +| Object | `{ "title": "asc" }` | +| Array of objects | `[{ "title": "asc" }, { "createdAt": "desc" }]` | + +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 + +The `list` tool accepts a `filters` parameter using Strapi's filter syntax: + +- **Field operators**: `$eq`, `$ne`, `$in`, `$notIn`, `$lt`, `$lte`, `$gt`, `$gte`, `$between`, `$contains`, `$notContains`, `$startsWith`, `$endsWith`, `$null`, `$notNull`, and their case-insensitive variants (`$eqi`, `$nei`, `$containsi`, `$notContainsi`, `$startsWithi`, `$endsWithi`). +- **Logical operators**: `$and`, `$or` (accept arrays of filter objects), `$not` (wraps a single filter object). +- **Implicit equality**: Passing a value directly (e.g., `{ "title": "Hello" }`) is equivalent to `{ "title": { "$eq": "Hello" } }`. + +Like sort fields, filter fields are constrained to scalar attributes only. + +#### Pagination + +The `list` tool also accepts `page` (1-indexed, default: 1) and `pageSize` (default: 25, max: 100) parameters. + + +### Permission boundaries + +The MCP server enforces the same permission model as the Strapi admin panel. Permissions are checked at multiple levels: + +1. **Tool visibility**: When an AI client connects, Strapi checks the Admin token's permissions and only exposes tools the token has access to. If the token does not grant `delete` on `Article`, the AI client will not see a delete tool for articles at all. + +2. **Field filtering**: Even within an exposed tool, input and output schemas are narrowed to the fields the token can access. If the token grants `read` on `Article` but excludes the `body` field, the AI client will not see or receive `body` content. Field restrictions are applied independently per action. Write schemas (`create`, `update`) only include fields permitted for the corresponding action. + +3. **Locale filtering**: When the [Internationalization (i18n)](/cms/features/internationalization) feature is enabled and locale-level permissions are configured, the `locale` parameter is narrowed per action. For example, a token might allow reading content in `en` and `fr` but only creating content in `en`. If the default locale is permitted for a given action, that locale is applied as the Zod schema default, so the AI client does not need to specify a locale explicitly. + +4. **Runtime enforcement**: Beyond schema-level narrowing, each handler calls Strapi's permission checker at runtime to verify access on the specific document being read, written, or published. Condition-based permissions (e.g., "only update entries you own") are enforced at this level. + +This means you can create tokens with fine-grained access: + +- A "read-only" token that only exposes listing and reading tools +- A token scoped to specific content types (e.g., articles but not categories) +- A token restricted to specific fields or locales +- A token with condition-based permissions (e.g., only update entries you own) + +:::tip +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. +::: + +### Stateless architecture + +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. + +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 + +The MCP server has the following limitations: + +- **Components**: Component fields are passed as untyped (`any`) in tool schemas. The AI client can read and write component data, but the schema does not describe the component's internal structure. +- **Dynamic zones**: Dynamic zone fields are passed as untyped arrays in tool schemas. +- **Relations**: Relation fields accept document IDs (e.g., `"z7v8zma53x01r6oceimv922b"`) as input. The advanced `connect`/`disconnect` relation syntax is not yet supported in MCP tool schemas. +- **Nested population parameters**: The `list` and `get` tools do not support nested population parameters for relations. +- **Media upload**: Media fields accept existing media asset references but the MCP server cannot upload new files. Use Strapi's media library or upload API to add files first, then reference them in MCP tool calls. +- **Custom fields**: Custom fields registered via plugins are mapped to their underlying Strapi type. If the custom field registry is not populated when MCP tools are registered, the custom field falls back to an `unknown` type. diff --git a/docusaurus/docs/snippets/strapi-ai-credits.md b/docusaurus/docs/snippets/strapi-ai-credits.md index 390f0928bc..2ebe137c71 100644 --- a/docusaurus/docs/snippets/strapi-ai-credits.md +++ b/docusaurus/docs/snippets/strapi-ai-credits.md @@ -3,7 +3,7 @@ Strapi AI includes 1,000 credits per month on the plan Lightweight actions use fewer credits, while more complex ones use more. You can check your credit usage in the of the admin panel. -Notifications are sent when your usage reaches 80%, 90%, and 100% of your monthly allowance. +Notifications are sent when your usage reaches 80%, 90%, and 100% of your monthly allowance. Overages apply. Credits are shared across all users within the same project instance. diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js index 431e089361..70afca443e 100644 --- a/docusaurus/sidebars.js +++ b/docusaurus/sidebars.js @@ -92,6 +92,14 @@ const sidebars = { label: 'Media Library', id: 'cms/features/media-library', }, + { + type: 'doc', + label: 'MCP server', + id: 'cms/features/strapi-mcp-server', + customProps: { + new: true, + }, + }, { type: 'doc', label: 'Preview', @@ -160,7 +168,7 @@ const sidebars = { label: 'Strapi AI for content managers', id: 'cms/ai/for-content-managers', customProps: { - new: true, + updated: true, }, }, { @@ -168,9 +176,14 @@ const sidebars = { label: 'AI for developers and docs', id: 'cms/ai/for-developers', customProps: { - new: true, + updated: true, }, }, + { + type: 'doc', + label: 'Docs MCP server', + id: 'cms/ai/docs-mcp-server', + }, ], }, { // APIs diff --git a/docusaurus/static/llms-code.txt b/docusaurus/static/llms-code.txt index 61c3e3e733..47eca924e2 100644 --- a/docusaurus/static/llms-code.txt +++ b/docusaurus/static/llms-code.txt @@ -1873,33 +1873,12 @@ export default { -# Strapi AI for content managers -Source: https://docs.strapi.io/cms/ai/for-content-managers - -## Activation and configuration -Description: All Strapi AI features can be enabled or disabled globally through the admin panel configuration: -(Source: https://docs.strapi.io/cms/ai/for-content-managers#activation) - -Language: JavaScript -File path: /config/admin.js|ts - -```js -module.exports = { - // ... - ai: { - enabled: true, // set to false to disable all Strapi AI features - }, -}; -``` - - - -# AI for developers -Source: https://docs.strapi.io/cms/ai/for-developers +# Docs MCP server +Source: https://docs.strapi.io/cms/ai/docs-mcp-server ## Connection details Description: Add to your .cursor/mcp.json file: -(Source: https://docs.strapi.io/cms/ai/for-developers#connection-details) +(Source: https://docs.strapi.io/cms/ai/docs-mcp-server#connection-details) Language: JSON File path: .cursor/mcp.json @@ -1929,6 +1908,41 @@ File path: .vscode/mcp.json } ``` +--- +Language: JSON +File path: ~/.codeium/windsurf/mcp_config.json + +```json + { + "mcpServers": { + "strapi-docs": { + "serverUrl": "https://strapi-docs.mcp.kapa.ai" + } + } + } +``` + + + +# AI for content managers +Source: https://docs.strapi.io/cms/ai/for-content-managers + +## Activation and configuration +Description: All Strapi AI features can be enabled or disabled globally through the admin panel configuration: +(Source: https://docs.strapi.io/cms/ai/for-content-managers#activation) + +Language: JavaScript +File path: /config/admin.js|ts + +```js +module.exports = { + // ... + ai: { + enabled: true, // set to false to disable all Strapi AI features + }, +}; +``` + # Strapi Client @@ -17225,13 +17239,13 @@ Source: https://docs.strapi.io/cms/configurations/features Description: (optional) If the server is running, stop it with Ctrl-C. (Source: https://docs.strapi.io/cms/configurations/features#enabling-a-future-flag) -Language: TypeScript -File path: /config/features.ts +Language: JavaScript +File path: /config/features.js -```ts +```js module.exports = ({ env }) => ({ future: { - adminTokens: env.bool('STRAPI_FUTURE_ADMIN_TOKENS', false), + experimental_firstPublishedAt: env.bool('STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT', false), }, }) ``` @@ -17241,7 +17255,7 @@ Language: DOTENV File path: .env ```dotenv - STRAPI_FUTURE_ADMIN_TOKENS=true + STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT=true ``` --- @@ -17249,11 +17263,11 @@ Language: TypeScript File path: /config/features.ts ```ts - export default { + export default ({ env }) => ({ future: { - adminTokens: env.bool('STRAPI_FUTURE_ADMIN_TOKENS', false), + experimental_firstPublishedAt: env.bool('STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT', false), }, - }; + }); ``` --- @@ -17261,7 +17275,7 @@ Language: DOTENV File path: .env ```dotenv - STRAPI_FUTURE_ADMIN_TOKENS=true + STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT=true ``` Language: Bash @@ -23926,6 +23940,149 @@ export default async function fetchContentType( +# MCP server +Source: https://docs.strapi.io/cms/features/strapi-mcp-server + +## Strapi code-based configuration +Description: Enable the MCP server by adding the mcp object to the server configuration file: +(Source: https://docs.strapi.io/cms/features/strapi-mcp-server#strapi-code-based-configuration) + +Language: JavaScript +File path: config/server.js + +```js +module.exports = ({ env }) => ({ + host: env('HOST', '0.0.0.0'), + port: env.int('PORT', 1337), + app: { + keys: env.array('APP_KEYS'), + }, + // highlight-start + mcp: { + enabled: true, + }, + // highlight-end +}); +``` + +--- +Language: TypeScript +File path: config/server.ts + +```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; +``` + + +## Advanced options +Description: | Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | Boolean | false | Enable or disable the MCP server. +(Source: https://docs.strapi.io/cms/features/strapi-mcp-server#advanced-options) + +Language: JavaScript +File path: config/server.js + +```js +mcp: { + enabled: true, + connectTimeoutMs: 10000, // 10 seconds + requestTimeoutMs: 120000, // 2 minutes +}, +``` + + +## Connecting Claude Desktop +Description: Add the Strapi MCP server to Claude's configuration file, as in the following example, replacing YOURADMINTOKEN with the admin token value copied from the admin panel: +(Source: https://docs.strapi.io/cms/features/strapi-mcp-server#connecting-claude-desktop) + +Language: JSON +File path: claude_desktop_config.json + +```json +{ + "mcpServers": { + "strapi-mcp": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "http://localhost:1337/mcp", + "--header", + "Authorization: Bearer YOUR_ADMIN_TOKEN" + ] + } + } +} +``` + + +## Connecting Claude Code +Description: Run the following command, replacing YOURADMINTOKEN with the admin token value copied from the admin panel: +(Source: https://docs.strapi.io/cms/features/strapi-mcp-server#connecting-claude-code) + +Language: JavaScript +File path: /Claude/claude_desktop_config.js + +```js +claude mcp add strapi-mcp --transport http http://localhost:1337/mcp -H "Authorization: Bearer YOUR_ADMIN_TOKEN" +``` + + +## Connecting Cursor +Description: Add the server to your .cursor/mcp.json file: +(Source: https://docs.strapi.io/cms/features/strapi-mcp-server#connecting-cursor) + +Language: JSON +File path: .cursor/mcp.json + +```json +{ + "mcpServers": { + "strapi-mcp": { + "type": "streamable-http", + "url": "http://localhost:1337/mcp", + "headers": { + "Authorization": "Bearer YOUR_ADMIN_TOKEN" + } + } + } +} +``` + + +## Connecting Windsurf +Description: Add the server to your ~/.codeium/windsurf/mcp_config.json file: +(Source: https://docs.strapi.io/cms/features/strapi-mcp-server#connecting-windsurf) + +Language: JSON +File path: ~/.codeium/windsurf/mcp_config.json + +```json +{ + "mcpServers": { + "strapi-mcp": { + "serverUrl": "http://localhost:1337/mcp", + "headers": { + "Authorization": "Bearer YOUR_ADMIN_TOKEN" + } + } + } +} +``` + + + # Users & Permissions Source: https://docs.strapi.io/cms/features/users-permissions diff --git a/docusaurus/static/llms-full.txt b/docusaurus/static/llms-full.txt index b150403f5b..e6e584c296 100644 --- a/docusaurus/static/llms-full.txt +++ b/docusaurus/static/llms-full.txt @@ -1861,14 +1861,18 @@ When evaluating editors, start with a plugin from the Marketplace for a quick tr -# Strapi AI for content managers +# AI for content managers Source: https://docs.strapi.io/cms/ai/for-content-managers -# Strapi AI for content management +# AI for content managers + +This page covers the AI-powered capabilities available to content managers in Strapi: the Strapi AI features built into the admin panel, and the MCP server that lets AI clients manage your content. + +## Strapi AI Some Strapi CMS features can be enhanced with Strapi AI, helping content managers and administrators design content structures, translate content automatically, and generate asset metadata, all from the admin panel. -## Activation and configuration {#activation} +### Activation and configuration {#activation} Strapi AI is available for Growth plan users since Strapi 5.30 and works with both Strapi Cloud and self-hosted deployments. To get started: @@ -1889,14 +1893,15 @@ module.exports = { See [Admin panel configuration > Strapi AI](/cms/configurations/admin-panel#strapi-ai) for all configuration options. -## Available features {#features} +### Available features {#features} | Feature | Description | |---------|-------------| | [Content-Type Builder](/cms/features/content-type-builder#strapi-ai) | AI chat assistant that helps design content-type structures, explain existing schemas, and plan data models. Uses your existing content types as context. | | [Internationalization](/cms/features/internationalization#ai-powered-internationalization) | Automatically translates content from the default locale to all other configured locales when you save an entry. | | [Media Library](/cms/features/media-library#ai-powered-metadata-generation) | Generates alternative text, captions, and descriptions for uploaded images. | -## Credits and data handling {#credits} + +### Credits and data handling {#credits} Strapi AI features consume AI credits. @@ -1904,6 +1909,10 @@ All AI requests are processed through Strapi-managed infrastructure. Content is See [Usage information > Strapi AI data handling](/cms/usage-information#strapi-ai-data-handling) for more details. +## Strapi MCP server + +Strapi includes a built-in [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that lets AI clients like Claude, Cursor, or any MCP-compatible tool manage your content through natural language. Once enabled and connected, an AI assistant can create, read, update, delete, publish, and unpublish entries directly through Strapi's Content Manager, all gated by admin token permissions. + # AI for developers @@ -1915,18 +1924,15 @@ The Strapi documentation site includes AI-powered tools to help developers learn :::tip AGENTS.MD files In addition to docs and product features described on the present page, the - - - -Once connected, your AI coding assistant can query the Strapi documentation directly to answer questions, suggest implementations, and verify API usage. ## Tips for better results {#tips} +The following tips will help you fine-tune your prompts to get the best results: +- Use the [Docs MCP server](/cms/ai/docs-mcp-server) in your IDE for the fastest developer experience. For docs-related questions, start your prompts with `Use the strapi-docs MCP server to answer:`. This will ensure the tool queries docs.strapi.io instead of creating answers based on its training data. - Include the page URL so the assistant grounds its answer in the right context. - Mention your Strapi version (e.g., Strapi 5) to avoid outdated suggestions. - Pair code examples with their source page when sharing snippets from `llms-code.txt`. - Prefer documented APIs over private internals when asking for code generation. -- Use the MCP server in your IDE for the fastest developer experience. @@ -7420,7 +7426,6 @@ Developers can use the following APIs to interact with future flags: | Property name | Related feature | Suggested environment variable name | | ------------- | --------------- | ---------------------------------- | | `experimental_firstPublishedAt` | [Draft & Publish](/cms/features/draft-and-publish#recording-the-first-publication-date) | `STRAPI_FUTURE_EXPERIMENTAL_FIRST_PUBLISHED_AT` | -| `adminTokens` | [Admin Tokens](/cms/features/admin-tokens) | `STRAPI_FUTURE_ADMIN_TOKENS` | @@ -8317,8 +8322,6 @@ If you're not the Strapi instance's super admin, the super admin must have grant ::: 4. Click on the **Save** button. The new Admin token will be displayed at the top of the interface, along with a copy button . - - :::caution The plaintext token key is shown only once, immediately after creation or regeneration. The `admin.secrets.encryptionKey` configuration that makes Content API token keys persistently viewable does not apply to Admin tokens. Admin token keys are always restricted to the token owner, regardless of encryption configuration. ::: @@ -9599,6 +9602,285 @@ To access the admin panel using a specific provider instead of logging in with a +# MCP server +Source: https://docs.strapi.io/cms/features/strapi-mcp-server + +# MCP server + +The MCP server exposes a set of content management tools to AI clients such as Claude Desktop, Claude Code, Cursor, or any MCP-compatible tool. An AI assistant 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 + +Before first use, the Strapi MCP server must be: +- configured in Strapi through the server configuration file and authenticated with Admin tokens created in the admin panel +- connected to your AI client. + +### Strapi admin panel configuration + +The MCP server authenticates requests using Admin tokens. Each MCP session is scoped to the permissions of the token used to connect: + +1. Create a new admin token (see [Creating an admin token](/cms/features/admin-tokens#creating-a-new-admin-token) on the Admin tokens feature page). +2. Copy the token as you will need it + +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. + +### Strapi code-based configuration + +Enable the MCP server by adding the `mcp` object to the server configuration file: + + + +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 + +The following optional keys can be added to the `mcp` configuration object: + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `enabled` | Boolean | `false` | Enable or disable the MCP server. | +| `connectTimeoutMs` | Number | `5000` | Maximum time (in ms) for the internal MCP transport to connect before the request is aborted. | +| `requestTimeoutMs` | Number | `60000` | Maximum time (in ms) for a single MCP request to complete before it times out. | + +```js title="config/server.js" +mcp: { + enabled: true, + connectTimeoutMs: 10000, // 10 seconds + requestTimeoutMs: 120000, // 2 minutes +}, +``` + +### AI client configuration + +Once you enabled and configured the MCP server through Strapi's admin panel (admin tokens) and configuration filters, you must connect your AI client to the Strapi MCP server. + +:::note +`localhost:1337/` is used in configuration examples on this page. If your Strapi server is hosted on another URL or port, please update the code accordingly. +::: + +#### Connecting Claude Desktop + +Open Claude Desktop's configuration file. The location varies depending on your system: + +| OS | File location | +|----|---------------| +| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | +| Windows | `%APPDATA%\Claude\claude_desktop_config.json` | + +:::tip +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. +::: + +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 [admin panel](#strapi-admin-panel-configuration): + +```json title="claude_desktop_config.json" +{ + "mcpServers": { + "strapi-mcp": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "http://localhost:1337/mcp", + "--header", + "Authorization: Bearer YOUR_ADMIN_TOKEN" + ] + } + } +} +``` + +Restart Claude Desktop for the changes to take effect. + +#### Connecting Claude Code + +Run the following command, replacing `YOUR_ADMIN_TOKEN` with the admin token value copied from the [admin panel](#strapi-admin-panel-configuration): + +```bash +claude mcp add strapi-mcp --transport http http://localhost:1337/mcp -H "Authorization: Bearer YOUR_ADMIN_TOKEN" +``` + +Restart Claude Code, then run `/mcp` to confirm `strapi-mcp` reports as connected. + +#### Connecting Cursor + +Add the server to your `.cursor/mcp.json` file: + +```json title=".cursor/mcp.json" +{ + "mcpServers": { + "strapi-mcp": { + "type": "streamable-http", + "url": "http://localhost:1337/mcp", + "headers": { + "Authorization": "Bearer YOUR_ADMIN_TOKEN" + } + } + } +} +``` + +#### Connecting Windsurf + +Add the server to your `~/.codeium/windsurf/mcp_config.json` file: + +```json title="~/.codeium/windsurf/mcp_config.json" +{ + "mcpServers": { + "strapi-mcp": { + "serverUrl": "http://localhost:1337/mcp", + "headers": { + "Authorization": "Bearer YOUR_ADMIN_TOKEN" + } + } + } +} +``` + +#### Connecting other MCP clients + +Any client that supports the MCP Streamable HTTP transport can connect. The generic configuration is as follows: + +| Setting | Value | +|---------|-------| +| Transport type | `streamable-http` | +| URL | `http://localhost:1337/mcp` (adjust host and port to your Strapi instance) | +| Authorization header | `Bearer YOUR_ADMIN_TOKEN` | + +## Usage + +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 + +#### Content-type tools + +For each content type the token has access to, Strapi generates up to 8 tools: + +| Tool | Action | Permission required | Description | +|------|--------|-------------------|-------------| +| `list` | Read | `read` | List entries with pagination, sorting, and filtering | +| `get` | Read | `read` | Get a single entry by document ID | +| `create` | Create | `create` | Create a new entry (created as draft if Draft & Publish is enabled) | +| `update` | Update | `update` | Update an existing entry by document ID | +| `delete` | Delete | `delete` | Delete an entry by document ID | +| `publish` | Publish | `publish` | Publish a draft entry | +| `unpublish` | Unpublish | `publish` | Unpublish a published entry | +| `discard_draft` | Discard draft | `publish` | Discard draft changes and revert to the published version | + +The last 3 tools (publish, unpublish, discard_draft) are only generated for content types that have [Draft & Publish](/cms/features/draft-and-publish) enabled. + +Tool names follow the pattern `cm___`. For example, an `Article` content type with UID `api::article.article` generates tools named `cm_api_article_list`, `cm_api_article_get`, `cm_api_article_create`, etc. + +Single types follow a similar pattern but include `_single_` in the name (e.g., `cm_api_homepage_single_get`). + +#### Built-in utility tools + +In addition to content-type tools, Strapi registers the following built-in tools: + +| Tool | Availability | Description | +|------|-------------|-------------| +| `log` | Development mode only | Logs a message to the Strapi server console at a specified level (`info`, `warn`, `error`, `http`, `log`). Useful for debugging MCP interactions. | + +Built-in utility tools are only available in development mode (when `autoReload` is enabled) and do not require specific content-type permissions. + +### Managing content through prompts + +Once connected, you can interact with your Strapi content using natural language: + +| Prompt | What happens | +|--------|-------------| +| "Create a new article titled 'Hello World' with body 'First post'." | Creates a draft article entry | +| "List the 5 most recent articles." | Returns paginated list, newest first | +| "Show me article with ID abc123." | Returns the full entry | +| "Update article abc123, change the title to 'Hello Strapi'." | Updates the title, other fields untouched | +| "Publish article abc123." | Flips the entry status to published | +| "Delete article abc123." | Removes the entry | + +### Understanding input schemas + +Each tool has an input schema derived from your content type's attributes. The schema is dynamically generated per session based on the token's permissions: + +- **Field-level permissions**: If the token restricts access to certain fields, those fields are excluded from both input and output schemas. For instance, a token that can only read `title` and `slug` on an `Article` type will only see those two fields in sort, filter, and output schemas. +- **Locale-level permissions**: If the [Internationalization (i18n)](/cms/features/internationalization) plugin is installed and the token restricts access to certain locales, the `locale` parameter only accepts the permitted locales for each action. Locale restrictions are evaluated per action: a token might allow reading in `en` and `fr` but only creating in `en`. +- **Write operations**: The `data` object in `create` and `update` tools only includes fields the token has permission to write. Unknown fields are rejected (strict validation). System-managed fields (`id`, `documentId`, `createdAt`, `updatedAt`, `publishedAt`, `createdBy`, `updatedBy`) and private fields are excluded automatically. +- **Attribute type mapping**: Field schemas carry constraints from your content-type definition, such as `required`, `minLength`, `maxLength`, `min`, `max`, and `enum` values. Enumeration fields expose their allowed values in the schema so the AI client can pick valid options. + +#### Sorting + +The `list` tool accepts a `sort` parameter that supports four notations: + +| Notation | Example | +|----------|---------| +| String | `"title:asc"` | +| Array of strings | `["title:asc", "createdAt:desc"]` | +| Object | `{ "title": "asc" }` | +| Array of objects | `[{ "title": "asc" }, { "createdAt": "desc" }]` | + +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 + +The `list` tool accepts a `filters` parameter using Strapi's filter syntax: + +- **Field operators**: `$eq`, `$ne`, `$in`, `$notIn`, `$lt`, `$lte`, `$gt`, `$gte`, `$contains`, `$notContains`, `$startsWith`, `$endsWith`, `$null`, `$notNull`, and their case-insensitive variants (`$eqi`, `$nei`, `$containsi`, etc.). +- **Logical operators**: `$and`, `$or` (accept arrays of filter objects), `$not` (wraps a single filter object). +- **Implicit equality**: Passing a value directly (e.g., `{ "title": "Hello" }`) is equivalent to `{ "title": { "$eq": "Hello" } }`. + +Like sort fields, filter fields are constrained to scalar attributes only. + +#### Pagination + +The `list` tool also accepts `page` (1-indexed, default: 1) and `pageSize` (default: 25, max: 100) parameters. + +#### Rich text (blocks) + +Rich text fields using the [Blocks editor](/cms/features/content-type-builder#rich-text-blocks) are represented with a structured schema in tool definitions. The schema covers all block types: paragraphs, headings (levels 1–6), quotes, code blocks (with optional language), ordered and unordered lists (including nested lists), images, and inline nodes (text with formatting marks, links). + +### Permission boundaries + +The MCP server enforces the same permission model as the Strapi admin panel. Permissions are checked at multiple levels: + +1. **Tool visibility**: When an AI client connects, Strapi checks the admin token's permissions and only exposes tools the token has access to. If the token does not grant `delete` on `Article`, the AI client will not see a delete tool for articles at all. + +2. **Field filtering**: Even within an exposed tool, input and output schemas are narrowed to the fields the token can access. If the token grants `read` on `Article` but excludes the `body` field, the AI client will not see or receive `body` content. Field restrictions are applied independently per action: write schemas (`create`, `update`) only include fields permitted for the corresponding action. + +3. **Locale filtering**: When the [Internationalization (i18n)](/cms/features/internationalization) plugin is installed and locale-level permissions are configured, the `locale` parameter is narrowed per action. For example, a token might allow reading content in `en` and `fr` but only creating content in `en`. If the default locale is permitted for a given action, it is applied as the Zod schema default so the AI client does not need to specify it explicitly. + +4. **Runtime enforcement**: Beyond schema-level narrowing, each handler calls Strapi's permission checker at runtime to verify access on the specific document being read, written, or published. Condition-based permissions (e.g., "only update entries you own") are enforced at this level. + +This means you can create tokens with fine-grained access: + +- A "read-only" token that only exposes listing and reading tools +- A token scoped to specific content types (e.g., articles but not categories) +- A token restricted to specific fields or locales +- A token with condition-based permissions (e.g., only update entries you own) + +:::tip +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. +::: + +### Stateless architecture + +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. This design means 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. + +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 + +The MCP server has the following limitations: + +- **Components**: Component fields are passed as untyped (`any`) in tool schemas. The AI client can read and write component data, but the schema does not describe the component's internal structure. +- **Dynamic zones**: Dynamic zone fields are passed as untyped arrays in tool schemas. +- **Relations**: Relation fields accept document IDs (e.g., `"z7v8zma53x01r6oceimv922b"`) as input. The advanced `connect`/`disconnect` relation syntax is not yet supported in MCP tool schemas. +- **Nested population parameters**: The `list` and `get` tools do not support nested population parameters for relations. +- **Media upload**: Media fields accept existing media asset references but the MCP server cannot upload new files. Use Strapi's media library or upload API to add files first, then reference them in MCP tool calls. +- **Custom fields**: Custom fields registered via plugins are mapped to their underlying Strapi type. If the custom field registry is not populated when MCP tools are registered, the field falls back to `unknown`. + + + # Users & Permissions Source: https://docs.strapi.io/cms/features/users-permissions diff --git a/docusaurus/static/llms.txt b/docusaurus/static/llms.txt index 2c293b0aa2..f009a05bb2 100644 --- a/docusaurus/static/llms.txt +++ b/docusaurus/static/llms.txt @@ -28,7 +28,7 @@ - [Logos](https://docs.strapi.io/cms/admin-panel-customization/logos): Update login and navigation logos by extending the admin app. Prefer SVG for crisp rendering; provide light/dark variants when possible for contrast. - [Theme extension](https://docs.strapi.io/cms/admin-panel-customization/theme-extension): Extend Strapi's admin panel theme. - [Customizing the rich text editor](https://docs.strapi.io/cms/admin-panel-customization/wysiwyg-editor): Learn more about the various strategies available to customize the WYSIWYG editor in Strapi's admin panel. -- [Strapi AI for content managers](https://docs.strapi.io/cms/ai/for-content-managers): Learn about AI-powered features in the Strapi admin panel, such as content-type design, automatic translations, and media metadata generation. +- [AI for content managers](https://docs.strapi.io/cms/ai/for-content-managers): Learn about AI-powered features in the Strapi admin panel and the built-in MCP server that lets AI clients manage your content. - [AI for developers](https://docs.strapi.io/cms/ai/for-developers): Use AI-powered tools on the Strapi documentation site. Chatbot, Copy Markdown, LLMs.txt files, Open with LLM, and MCP server for IDE integration. - [Strapi Client](https://docs.strapi.io/cms/api/client): The Strapi Client library simplifies interactions with your Strapi back end, providing a way to fetch, create, update, and delete content. - [Content API](https://docs.strapi.io/cms/api/content-api): Learn more about Strapi 5's Content API @@ -99,6 +99,7 @@ - [Releases](https://docs.strapi.io/cms/features/releases): Releases group entries into publishable batches to trigger simultaneous publish or unpublish actions across content types and locales. Instructions in this documentation detail creating releases, adding entries, and understanding plan limitations. - [Review Workflows](https://docs.strapi.io/cms/features/review-workflows): Review Workflows define custom multi-stage pipelines for content review, facilitating collaboration from draft to publication. This documentation walks through creating workflows and assigning stages. - [Single Sign-On (SSO)](https://docs.strapi.io/cms/features/sso): Single Sign-On (SSO) lets administrators authenticate via identity providers such as Azure AD instead of local passwords. Configuration steps in this documentation cover enabling SSO and mapping roles. +- [MCP server](https://docs.strapi.io/cms/features/strapi-mcp-server): 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. - [Users & Permissions](https://docs.strapi.io/cms/features/users-permissions): Users & Permissions manages end-user accounts, JWT-based authentication, and role-based access to APIs. This documentation explains how to create roles, configure permissions, and secure access to your content API. - [Installation](https://docs.strapi.io/cms/installation): Learn many different options to install Strapi and getting started on using it. - [Additional resources for migrating to Strapi 5](https://docs.strapi.io/cms/migration/v4-to-v5/additional-resources/introduction): The following pages cover some dedicated topics for specific use cases when upgrading to Strapi 5. Please ensure you have read the [introduction to up...