# Payload CMS MCP > Payload CMS MCP lets your AI client interact with complex headless content management systems directly. It provides structured tools for reading, writing, and updating data across collections, singletons, and custom schemas without needing hand-written API endpoints. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Tags:** schema-validation, json-api, database-management, content-orchestration, node-framework, rest-api ## Description You can tell your AI agent to manage your website's backend data as if it were a native interface. Instead of building complex code just to fetch or write content, you simply ask for the action—like listing all posts in a collection or updating a specific JSON field on a profile document. Your agent handles the Payload CMS logic automatically, letting you focus on generating the final output, not managing the database plumbing. For example, if you need to update a global site setting, your AI client can execute that change with minimal prompts. Connecting this MCP via Vinkius gives your agent access to over 4,000 other tools, meaning it's one place for all your data needs. You write the prompt; your AI handles the database interaction. ## Tools ### create_cms_document Write new, fully structured JSON documents into designated Payload collections. ### wipe_cms_document Permanently remove specific document rows from the active CMS collection. ### get_single_document Inspect deep internal arrays to retrieve data for a single, specified record. ### get_singleton_global Extract properties that control global settings or site-wide configurations. ### list_collection_documents Find and list all the available structured data types within your CMS collections. ### list_payload_users List active user accounts, checking which admin identities are currently set up. ### verify_token_identity Check the current user's identity and permissions associated with the API token. ### search_collection_where Perform advanced searches across a collection based on specific criteria or filters. ### patch_cms_document Modify and update existing documents by substituting specific database blocks using their ID. ### update_singleton_global Dispatch an automated check to ensure global settings are correctly updated across the system. ## Prompt Examples **Prompt:** ``` List standard explicit documents isolated under the 'posts' collection. ``` **Response:** ``` Called target schema mapping collection 'posts'. Pulled 3 documents natively limit parameters. Docs map details: 1 (ID: a3...), Status: Published. 2 (ID: a4...). Shall I explore JSON content inside ID a3? ``` **Prompt:** ``` Create natively new doc under 'categories', set JSON data `{ "name": "Tech" }`. ``` **Response:** ``` Payload confirmed endpoint bounding execution. Created efficiently! New ID assigned logically is '8z9xy2'. Target fields updated explicitly mapping to `{ "name": "Tech" }`. Waiting for next workflow boundaries. ``` **Prompt:** ``` Wipe document logically bounding the ID 'abc12' from the 'media' collection. ``` **Response:** ``` Initiated DELETE binding rules. Headless API verified action gracefully. Document ID explicitly 'abc12' has been purged completely from the active 'media' target collection. ``` ## Capabilities ### Create new content documents The MCP writes brand new JSON documents into specified Payload collections. ### Update existing data fields It patches specific fields within a document or collection using its unique ID. ### Find single site settings You can extract configuration details from global, singular items that control the entire website. ### List all content collections The MCP scans and retrieves the list of structured data types available in your CMS. ### Identify specific users or roles It queries existing user records to check permissions or find active admin accounts. ## Use Cases ### Staging a new feature page The content engineer needs to test how the site handles 20 different product descriptions. Instead of manually running 20 API calls, they ask their agent to run `list_collection_documents` for 'products' and then loop through the results, using `get_single_document` on each one to validate its structure. ### Fixing a broken site setting The frontend team notices the primary navigation header is wrong. They ask their agent to use `get_singleton_global` to retrieve the current global settings, spot the error, and then use `patch_cms_document` to correct just the title field. ### Deprecating old content An admin needs to remove an entire outdated media gallery. Instead of running a complex deletion script, they tell their agent to target and wipe the specific record using `wipe_cms_document` by its ID. ### Auditing user permissions The security team wants to know if only admins can create new content. They prompt their agent to run `list_payload_users`, then use the results to check which roles have permission to perform a write operation. ## Benefits - Instead of writing boilerplate code to read data, you can simply ask the agent to list all documents in a collection using `list_collection_documents`. This saves hours of repetitive API setup. - Need to make a change? Use `patch_cms_document` to modify fields on an existing document without having to write full update scripts. It targets specific blocks by ID, making the action precise. - The MCP handles complex validation for you. If your site relies on global settings, use `get_singleton_global` to pull that configuration state and test your logic against it immediately. - Content lifecycle management gets easier with tools like `create_cms_document`. You can instruct the agent to write a new post or category record simply by providing the JSON data payload. - Don't waste time figuring out who has access. Use `list_payload_users` and `verify_token_identity` to audit your system's user roles before deploying any major changes. ## How It Works The bottom line is you get a natural language way to control and manipulate complex database structures. 1. First, you subscribe and provide your specific Payload Base URL and private API token parameters. 2. Next, you tell your AI client exactly what data you need—for example, 'list all documents in the posts collection' or 'update the site title to X'. 3. The MCP runs the command against your CMS, returning structured JSON data that your agent can immediately use for the next step. ## Frequently Asked Questions **How do I find out what collections exist in Payload CMS using the Payload CMS MCP?** You use `list_collection_documents`. This tool scans your entire setup and returns a list of all structured data types, letting you know exactly where to look for content. **Can I update global site settings with the Payload CMS MCP?** Yes. You use `patch_cms_document` or `update_singleton_global`. These tools are designed specifically to manage those crucial, site-wide configuration items. **Is the payload cms mcp safe for deleting content?** It is safe when used correctly. The MCP provides `wipe_cms_document` to irreversibly delete specific records after your agent has verified which documents need removal. **Does Payload CMS MCP work with my private API key?** Yes, you provide the required Private API Token when setting up the connection. This ensures that only authorized calls can manipulate your backend data.