Terminal
Terminal/Skill
Shows Strapi 5 plugin developers how to add custom MCP tools, prompts and resources that AI clients can call.
By Strapi
Works with
npx skills add strapi/skills --skill strapi-mcp-capabilitiesRegister custom MCP tools/prompts/resources so AI clients can trigger plugin-specific actions on a running Strapi instance. Strapi 5.47.0+. API source of truth: @strapi/types, search mcp.
config/server.ts must set mcp: { enabled: true }. Endpoint is POST /mcp.register() phase. The capability list is locked once the MCP server starts (during bootstrap). Registering later throws.@strapi/utils (import { z } from '@strapi/utils'), not standalone zod.strapi at module top-level. Either register inline (have strapi) or use ai.mcp.defineTool(...) to define at module scope, then register with the injected strapi.Inline — when strapi is in scope (a function called from register()):
// mcp/tools/get-store-kpis.ts
import type { Core } from '@strapi/strapi';
import { z } from '@strapi/utils';
export const registerGetStoreKpisTool = (strapi: Core.Strapi) => {
strapi.ai.mcp.registerTool({ /* definition */ });
};
Builder — define at module scope (no strapi), register later. defineTool is an identity helper that narrows the access variant for type inference:
// mcp/tools/get-top-products.ts
import { ai } from '@strapi/strapi';
import { z } from '@strapi/utils';
export const getTopProductsTool = ai.mcp.defineTool({ /* definition */ });
// register.ts
strapi.ai.mcp.registerTool(getTopProductsTool);
Wire both from the plugin register():
// register.ts
export const register = ({ strapi }: { strapi: Core.Strapi }) => {
registerGetStoreKpisTool(strapi); // inline
strapi.ai.mcp.registerTool(getTopProductsTool); // builder
};
strapi.ai.mcp.registerTool({
name: 'get_store_kpis', // snake_case, unique
title: 'Get Store KPIs',
description: 'What it returns + when to use it. The AI reads this to choose the tool.',
auth: { policies: [{ action: 'plugin::store-analytics.read' }] }, // OR devModeOnly: true
resolveInputSchema: () => inputSchema, // optional; omit if no args
resolveOutputSchema: () => outputSchema, // required; a z.object
createHandler: (strapi, context) => async ({ args, extra }) => {
const result = await strapi
.plugin('store-analytics')
.service('analytics')
.getStoreKpis(args);
return {
content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
structuredContent: result, // must match resolveOutputSchema
};
},
});
Key points:
createHandler(strapi, context) => handler. The handler receives a single object { args, extra }. args is z.infer<inputSchema> (typed); if no resolveInputSchema, omit args.context: { userAbility, user } — use userAbility for entity/field permission checks and user (token owner) for setCreatorFields on writes.name/title/description/resolveOutputSchema are required. description quality drives AI tool selection — state what it returns and when to use it.z.object input/output schemas; reuse shared field schemas (e.g. an isoDateSchema with .describe(...))..describe() every non-obvious field — descriptions reach the AI client.structuredContent returned by the handler must satisfy resolveOutputSchema.auth: { policies: [{ action, subject? }] } — CASL check; session passes if the token's ability satisfies any policy. action is typically a registered admin permission, e.g. plugin::<plugin-id>.<permission>.devModeOnly: true — no auth; only available when autoReload is on (dev). Use for debug tools.For auth to be grantable to a token, register the permission action in bootstrap():
await strapi.service('admin::permission').actionProvider.registerMany([
{ section: 'plugins', displayName: 'Access store analytics',
uid: 'read', pluginName: 'store-analytics' },
]);
// → action becomes 'plugin::store-analytics.read'
// success
return { content: [{ type: 'text', text }], structuredContent: result };
// error
return { content: [{ type: 'text', text: 'message' }], isError: true };
structuredContent and isError are mutually exclusive.
server/src/
├── register.ts # calls registrations (register phase only)
├── bootstrap.ts # registerMany permission actions
├── mcp/
│ ├── index.ts # registerAllMcpTools(strapi)
│ ├── schemas.ts # shared zod field schemas
│ └── tools/<tool>.ts # one capability per file
└── services/ # business logic the handlers call
mcp: { enabled: true } in config/server.ts; restart Strapi.http://localhost:1337/mcp with Authorization: Bearer <admin-token> whose permissions include the tool's auth action.structuredContent matching its output schema.Same lifecycle/auth rules, different builders: ai.mcp.definePrompt / strapi.ai.mcp.registerPrompt and ai.mcp.defineResource / strapi.ai.mcp.registerResource. See reference.md for their field tables and signatures.
@strapi/types