Strapi MCP Server

Instructions

Implementation Reference

• src/index.ts:1678-1769 (handler)

  The core handler function that executes the strapi_rest tool logic: validates authorization for writes, constructs the request URL with params, makes the fetch call to Strapi, logs performance, and handles the response/error.
  async function makeRestRequest( serverName: string, endpoint: string, method: string = 'GET', params?: Record<string, any>, body?: Record<string, any>, userAuthorized: boolean = false, requestId?: string ): Promise<any> { // Check for write operations that require explicit user authorization if ((method === 'POST' || method === 'PUT' || method === 'DELETE') && !userAuthorized) { throw new McpError( ErrorCode.InvalidParams, `AUTHORIZATION REQUIRED: ${method} operations require explicit user authorization.\n\n` + `IMPORTANT: The client MUST:\n` + `1. Ask the user for explicit permission before making this request\n` + `2. Show the user exactly what data will be modified\n` + `3. Receive clear confirmation from the user\n` + `4. Set userAuthorized=true when making the request\n\n` + `This is a security measure to prevent unauthorized data modifications.` ); } const serverConfig = getServerConfig(serverName); let url = `${serverConfig.API_URL}/${endpoint}`; // Parse query parameters if provided if (params) { const queryString = qs.stringify(params, { encodeValuesOnly: true }); if (queryString) { url = `${url}?${queryString}`; } } const headers = { 'Authorization': `Bearer ${serverConfig.JWT}`, 'Content-Type': 'application/json', }; const requestOptions: RequestInit = { method, headers, }; if (body && (method === 'POST' || method === 'PUT')) { requestOptions.body = JSON.stringify(body); } const startTime = Date.now(); logger.debug(`Making REST request to Strapi`, { requestId, server: serverName, endpoint, method, hasParams: !!params, hasBody: !!body, userAuthorized, url: url.replace(serverConfig.JWT, '[REDACTED]') }); try { const response = await fetch(url, requestOptions); const duration = Date.now() - startTime; logger.logApiCall( requestId || 'unknown', method, endpoint, duration, response.status, serverName ); return await handleStrapiError(response, `REST request to ${endpoint}`, requestId); } catch (error) { const duration = Date.now() - startTime; logger.error(`REST request to ${endpoint} failed`, { requestId, server: serverName, endpoint, method, duration, errorType: error instanceof Error ? error.constructor.name : typeof error }, error instanceof Error ? error : undefined); throw error; } }
• src/index.ts:504-562 (schema)

  Zod schema defining input validation for the strapi_rest tool, including server, endpoint, method, params, body, and userAuthorized flag with refinement for write ops.
  const RestSchema = z.object({ server: z.string().min(1, "Server name is required and cannot be empty"), endpoint: z.string().min(1, "Endpoint is required and cannot be empty"), method: z.enum(["GET", "POST", "PUT", "DELETE"], { errorMap: () => ({ message: "Method must be one of: GET, POST, PUT, DELETE" }) }).optional().default("GET"), params: z.union([ z.record(z.any()), z.string().transform((str, ctx) => { try { return JSON.parse(str); } catch (e) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Params must be a valid JSON object or object" }); return z.NEVER; } }) ]).optional(), body: z.union([ z.record(z.any()), z.string().transform((str, ctx) => { try { return JSON.parse(str); } catch (e) { ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Body must be a valid JSON object or object" }); return z.NEVER; } }) ]).optional(), userAuthorized: z.union([ z.boolean(), z.string().transform((str, ctx) => { if (str === "true") return true; if (str === "false") return false; ctx.addIssue({ code: z.ZodIssueCode.custom, message: "userAuthorized must be boolean true/false or string 'true'/'false'" }); return z.NEVER; }) ]).optional().default(false) }).strict().refine( (data) => { // For write operations, ensure userAuthorized is explicitly set to true if (["POST", "PUT", "DELETE"].includes(data.method) && !data.userAuthorized) { return false; } return true; }, { message: "Write operations (POST, PUT, DELETE) require explicit user authorization (userAuthorized: true)", path: ["userAuthorized"] } );
• src/index.ts:1288-1344 (registration)

  Tool registration in the ListTools handler: defines name, detailed description with examples, and inputSchema derived from Zod schema.
  name: "strapi_rest", description: "Execute REST API requests against Strapi endpoints. IMPORTANT: All write operations (POST, PUT, DELETE) require explicit user authorization via the userAuthorized parameter.\n\n" + "1. Reading components:\n" + "params: { populate: ['SEO'] } // Populate a component\n" + "params: { populate: { SEO: { fields: ['Title', 'seoDescription'] } } } // With field selection\n\n" + "2. Updating components (REQUIRES USER AUTHORIZATION):\n" + "body: {\n" + " data: {\n" + " // For single components:\n" + " componentName: {\n" + " Title: 'value',\n" + " seoDescription: 'value'\n" + " },\n" + " // For repeatable components:\n" + " componentName: [\n" + " { field: 'value' }\n" + " ]\n" + " }\n" + "}\n" + "userAuthorized: true // Must set this to true for POST/PUT/DELETE after getting user permission\n\n" + "3. Other parameters:\n" + "- fields: Select specific fields\n" + "- filters: Filter results\n" + "- sort: Sort results\n" + "- pagination: Page through results", inputSchema: { ...zodToJsonSchema(ToolSchemas.strapi_rest), properties: { ...zodToJsonSchema(ToolSchemas.strapi_rest).properties, server: { ...zodToJsonSchema(ToolSchemas.strapi_rest).properties.server, description: "The name of the server to connect to" }, endpoint: { ...zodToJsonSchema(ToolSchemas.strapi_rest).properties.endpoint, description: "The API endpoint (e.g., 'api/articles')" }, method: { ...zodToJsonSchema(ToolSchemas.strapi_rest).properties.method, description: "HTTP method to use", default: "GET" }, params: { ...zodToJsonSchema(ToolSchemas.strapi_rest).properties.params, description: "Optional query parameters for GET requests. For components, use populate: ['componentName'] or populate: { componentName: { fields: ['field1'] } }" }, body: { ...zodToJsonSchema(ToolSchemas.strapi_rest).properties.body, description: "Request body for POST/PUT requests. For components, use: { data: { componentName: { field: 'value' } } } for single components or { data: { componentName: [{ field: 'value' }] } } for repeatable components" }, userAuthorized: { ...zodToJsonSchema(ToolSchemas.strapi_rest).properties.userAuthorized, description: "REQUIRED for POST/PUT/DELETE operations. Client MUST obtain explicit user authorization before setting this to true.", default: false } } },
• src/index.ts:1583-1596 (handler)

  Dispatch handler in CallToolRequestSchema: validates input, extracts params, calls the makeRestRequest handler, and formats response.
  // Validate input using Zod (includes authorization check) const validatedArgs = validateToolInput("strapi_rest", args, requestId); const { server, endpoint, method, params, body, userAuthorized } = validatedArgs; logger.startRequest(requestId, name, server); const data = await makeRestRequest(server, endpoint, method, params, body, userAuthorized, requestId); result = { content: [ { type: "text", text: JSON.stringify(data, null, 2), }, ], };
• src/index.ts:1772-1813 (helper)

  Helper function used by the handler to process Strapi responses, extract errors with hints, log, and throw McpError if failed.
  async function handleStrapiError(response: Response, context: string, requestId?: string): Promise<any> { if (!response.ok) { let errorMessage = `${context} failed with status: ${response.status}`; let errorData: any = null; try { errorData = await response.json() as any; if (errorData && typeof errorData === 'object' && 'error' in errorData) { errorMessage += ` - ${errorData.error?.message || JSON.stringify(errorData.error)}`; // Add helpful hints based on status if (response.status === 400) { errorMessage += "\nHINT: Check the request structure matches Strapi's expectations. For v4/v5 differences, refer to Strapi's migration guide."; } else if (response.status === 404) { errorMessage += "\nHINT: Check the endpoint path and ID are correct."; } } } catch { errorMessage += ` - ${response.statusText}`; } logger.error(`Strapi API error: ${context}`, { requestId, status: response.status, statusText: response.statusText, url: response.url, errorData: errorData, context }); throw new McpError(ErrorCode.InternalError, errorMessage); } logger.debug(`Strapi API success: ${context}`, { requestId, status: response.status, url: response.url }); return response.json(); }