# Payload CMS Extended MCP > Payload CMS Extended connects your AI agent directly to your headless CMS instance. It lets you query collections, inspect document JSON payloads, and perform full CRUD operations—creating, reading, updating, or deleting data—all through natural conversation. This means you manage content without ever opening the Payload Admin panel. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** payload-cms, typescript, api-framework, database-management, content-api ## Description You're connecting your AI agent straight to your Payload CMS backend. This isn't just a wrapper; it lets you manage and manipulate all your content data—creating, reading, updating, or deleting records—without ever opening the actual Payload Admin panel. Your agent gets deep access to your entire data model through natural conversation. ### Data Awareness: Knowing What You Got You don't need to switch between your code editor and the CMS console just to verify a field name or check an ID number. The server lets you discover what data exists first. Use `list_collections` to see every collection defined in your schema, giving you a map of all available content types. You can also call `get_global` to fetch system-level configuration and global settings stored outside of any specific collection. To find documents, use `list_documents`. This tool lets you search across collections using plain language queries while applying complex filters, specifying sorting parameters, or managing pagination limits. If you need the complete picture for one document, call `get_document` with a unique ID; this action returns the full JSON payload, revealing every field and relationship associated with that specific entry. ### Content Manipulation: Writing to Your CMS The server gives your agent full write access. You can create brand new documents in any collection using `create_document`. When content changes, you modify existing records by calling `update_document` with the target ID and the new data payload. If a record is obsolete, you can permanently delete it using `delete_document`. Beyond collections, you manage system-wide settings directly by running `update_global`, allowing your agent to change configuration values that affect the whole site. ### Authentication and Context Control Because these are sensitive operations, managing user context is key. To start working, you'll first use `login_user` with credentials; this action provides an active session token needed for all subsequent calls. You can verify who your agent is acting as by running `get_me`, which returns details about the currently authenticated user session. When you're done or need to switch users, call `logout_user` to end the current session and invalidate tokens. If the access token expires during a long workflow, you won't be locked out; you just use `refresh_token` with your stored refresh token to grab a new, valid access token for continued operation. ## Tools ### create_document Creates a brand new document entry within any specified collection. ### delete_document Permanently deletes an existing document record by its ID. ### get_document Retrieves the full data payload for a single document using its unique ID. ### get_global Fetches configuration or system settings stored in the CMS global data area. ### get_me Returns details about the currently authenticated user session. ### list_documents Lists documents from a collection, supporting optional query strings for filtering, sorting, and pagination. ### login_user Authenticates a user account by providing credentials to get an active session token. ### logout_user Ends the current user's session and invalidates authentication tokens. ### refresh_token Uses a stored refresh token to obtain a new, valid access token for continued API use. ### update_document Modifies the content of an existing document in a collection using its ID and new data payload. ### update_global Changes system-wide configuration or global settings defined in the CMS. ## Prompt Examples **Prompt:** ``` List all the collections available in my Payload CMS. ``` **Response:** ``` I've accessed your Payload instance. You have 4 active collections: 'Users', 'Posts', 'Categories', and 'Media'. You also have a global called 'Site-Settings'. Which one would you like to explore? ``` **Prompt:** ``` Find the post with the slug 'announcing-mcp-support' in the 'posts' collection. ``` **Response:** ``` Searching... I found one document in 'posts' matching that slug. The ID is `65a2b...`, the status is 'published', and it was last updated on Oct 24th. Would you like the full content of this post? ``` **Prompt:** ``` Get the full details for document ID 64f123456789 in the 'products' collection. ``` **Response:** ``` Retrieving document... Here are the details for 'Wireless Headphones' (ID: 64f123456789). It has a price of $199, stock level of 45, and is linked to the 'Electronics' category. I've also retrieved the associated image metadata. ``` ## Capabilities ### Discover Collections and Globals List every collection and global setting defined in your CMS schema so you know exactly what data exists. ### Search and Filter Documents Find specific documents across any collection using natural language queries, applying filters, sorting, or pagination parameters. ### Read Full Data Payloads Retrieve the complete JSON payload for a document ID, showing all associated fields and relationships. ### Create and Update Records Build or modify entire documents in any collection using structured data input directly from your AI client. ### Manage Authentication Log into, log out of, and refresh user sessions to ensure the agent has the necessary credentials for sensitive operations. ## Use Cases ### Fixing a broken content link. A Content Manager notices an article links to missing product data. Instead of navigating the CMS manually, they tell their agent: 'Check the `Products` collection for all documents with status 'draft' that are linked to ID 456.' The agent runs `list_documents`, identifies the broken entries, and reports them back immediately. ### Verifying data during a feature build. A Developer needs to confirm if their new user profile field (`bio`) exists in the database. They ask: 'Show me the schema for the `Users` collection.' The agent runs internal discovery tools and reports back the exact structure, saving hours of guesswork. ### Deploying urgent site settings changes. A DevOps Engineer needs to change the primary contact email displayed across the entire site. They ask: 'Update the global setting for Primary Contact Email.' The agent runs `update_global` with the new value, confirming the change without needing admin UI access. ### Bulk updating outdated records. A Content Manager finds that all articles published last year need a status update. They ask: 'Find all documents in `Posts` where published_date is before 2023-01-01 and change their status to 'archived'.' The agent runs the query (via `list_documents`) and executes bulk updates using `update_document`. ## Benefits - Stop context switching. Instead of opening the Payload Admin panel to check a field name or entry status, you simply ask your agent. It handles the query using `list_documents` and gives you the answer right in the chat window. - Manage credentials without manual steps. Use `login_user`, `get_me`, and `refresh_token` so your AI client can operate with up-to-date, authenticated access for every operation. - Deep data inspection is instant. If you need to know how a document relates to another—like checking associated image metadata—you call `get_document` and get the full JSON payload immediately. - Built-in content lifecycle control. You don't just read; you write. Use `create_document` or `update_document` to push new drafts or modify published records without writing a single line of backend code. - System configuration is exposed. Want to know what the site's main settings are? Call `get_global` and get the data structure for system-wide variables, which is way faster than digging through config files. ## How It Works The bottom line is, you treat your CMS like it's just another data source—you talk to it instead of clicking through multiple admin tabs. 1. Subscribe to this server and provide your Payload CMS Instance URL and API Key. 2. Your AI client uses the available tools (e.g., `list_documents` or `get_global`) to understand your data structure. 3. You issue a command in plain English (e.g., 'Find all posts by Author X that are published'). The agent executes the necessary API calls and returns structured results. ## Frequently Asked Questions **How does the Payload CMS Extended MCP Server handle authentication?** It manages standard session flow. You use `login_user` to get a token, and your agent uses `refresh_token` if that token expires before you finish your tasks. **Can I list every collection using the list_documents tool?** You don't use `list_documents` for discovery. You ask the server to discover collections first, which tells you what data structures are available before running any queries. **Is it safe to run update_document through the AI agent?** Yes, but your client needs proper API keys and permissions. The tool requires specific instructions on *what* to change and *which* document ID you're targeting. **What if I need to check system settings not in a collection?** You use the `get_global` tool. This lets your agent read data stored outside of standard collections, like site-wide configuration flags or API keys defined as globals. **When using the list_documents tool, what query syntax do I use to filter by multiple criteria?** You pass a structured JSON object as the query parameter. This lets you combine filters—for instance, finding documents where 'status' equals 'published' AND 'category' is in ['tech', 'finance']. The agent handles the complex filtering logic for you. **If I run delete_document, how can I confirm I'm deleting the correct record?** The agent requires explicit confirmation of the document ID and collection name before executing a deletion. It shows you the full payload details first, ensuring you don’t accidentally wipe out critical data. **Does get_document return all associated nested fields and relationships?** Yes, it fetches the complete JSON payload for that single document. This means you get access to all linked data structures and relationship metadata defined in your Payload CMS schema. **How do I maintain my session if my API token expires while using other tools?** Use the refresh_token tool when you encounter an authorization error. This automatically validates and replaces the expired credentials, keeping your AI client connected and operational without manual intervention. **How can I see all the available content types in my Payload instance?** You can use the `list_collections` tool. Your agent will query your Payload instance and return a list of all registered collections and globals, helping you understand what data is available to interact with. **Is it possible to search for documents with specific criteria, like a slug or status?** Yes! Use the `find_documents` tool. You can provide a collection name and filter parameters (e.g., `where[slug][equals]=my-post`). The agent will return the matching documents including their full metadata. **Can I retrieve the full data of a single document if I have its ID?** Absolutely. Use the `get_document` tool by providing the collection name and the unique Document ID. This is perfect for inspecting deep nested relationships or specific field values.