# Payload CMS MCP for AI Agents AI Agent Connect

> Payload CMS MCP connects your AI agent to the Payload CMS Local REST API. It lets you handle document collections, update global singletons, and manage user identities without leaving your IDE. Use it to push JSON updates, wipe data, or verify user permissions instantly.

## Overview
- **Category:** loved-by-devs
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_pZpYFZ91zptyRj8xfAztMAlS3X7lYKaWp9OCjepv/ai-agent-connect
- **Tags:** schema-validation, json-api, database-management, content-orchestration, node-framework, rest-api

## Description

Moving data between your code and a headless CMS usually involves a lot of context switching. You find yourself jumping back to a dashboard, copy-pasting JSON, and manually hitting save just to update a single global setting or a few content blocks. It feels like a chore when you're in the middle of a flow. This Connector cuts out the middleman. By connecting your AI client directly to the Payload CMS Local REST API, you can just tell your agent what needs to happen. If you need to push a new set of pricing data, create a batch of category documents, or check the current state of a singleton, the agent handles the request for you. It understands your specific database schemas and follows your established rules for document collections. Since Vinkius makes managing these connections simple, you can focus on building the frontend or refining the content strategy while the agent handles the data entry and mutations. It turns your CMS from a separate tab into an active part of your development environment. You can iterate on content structure faster because the agent can see the actual data. Instead of guessing how a response will look, you can have your agent pull the real data from the collection to verify your frontend components are mapping correctly. It's a more direct way to work with your content.

## Tools

### list_collection_documents
Show you the documents and routing spaces inside your headless collections. It helps you see what's currently in your database.

### list_payload_users
List the active admin identities and user accounts in your system. Use this to audit your current user base.

### search_collection_where
Search through your collections using specific query filters. Find exactly what you need without manual browsing.

### patch_cms_document
Update specific data blocks within a document using its ID. This lets you change parts of a document without rewriting it.

### update_singleton_global
Push updates to your global configuration settings automatically. Use this to change site-wide variables instantly.

### get_single_document
Fetch a specific document to see its internal data structure. This is useful for verifying the exact shape of your content.

### get_singleton_global
Pull the properties that drive your active global singleton settings. Use this to see your site's current configuration.

### verify_token_identity
Check the rules and permissions attached to the current user. This is great for debugging access issues.

### create_cms_document
Create a new document by writing a JSON payload into a collection. Use this to add new content via natural language.

### wipe_cms_document
Delete a specific document row from your live database. This allows you to purge test data quickly.

## Prompt Examples

**Prompt:** 
```
Can you show me what's in the 'products' collection?
```

**Response:** 
```
I've pulled the current documents from your 'products' collection. Here is the summary:

| Product Name | SKU | Status |
| :--- | :--- | :--- |
| Wireless Headphones | WH-1000 | Published |
| Bluetooth Speaker | BS-500 | Draft |
| Smart Watch | SW-20 | Published |

Would you like to see the full JSON details for any of these?
```

**Prompt:** 
```
Update the site title in the global settings to 'Summer Sale 2024'.
```

**Response:** 
```
I've updated the global settings for you. The site title is now set to **Summer Sale 2024**. I've also verified that the change was successfully pushed to your CMS.
```

**Prompt:** 
```
Who are the current admin users?
```

**Response:** 
```
Here are the active admin identities currently registered in your Payload CMS:

- **Admin_01**: admin@example.com (Full Access)
- **Editor_02**: editor@example.com (Content Only)
- **Dev_User**: dev@example.com (Read Only)

Let me know if you need to check the permissions for any specific user.
```

## Capabilities

### Create new content documents
Write new JSON payloads into your specified collections instantly.

### Update existing JSON data
Modify specific blocks of data within your documents using their unique IDs.

### Retrieve global configuration settings
Pull the properties that drive your active global singleton settings.

### List and filter active users
Identify and list the active admin identities and user accounts in your system.

### Delete specific content nodes
Permanently remove specific document rows from your live database.

### Search for content using query filters
Find specific content items using natural language and query filters.

## Use Cases

### Toggle maintenance mode
A developer needs to update a 'Maintenance Mode' flag in the global settings. The dev asks the agent to toggle the flag, and the agent calls `update_singleton_global` to update the site instantly.

### Bulk-upload products
A content engineer wants to bulk-upload 20 new 'Product' items from a JSON file. The engineer provides the blob and the agent uses `create_cms_document` to populate the collection in seconds.

### Purge test media
A QA tester needs to wipe out all 'Test' records in the media collection. The tester asks to clear out the test media, and the agent uses `wipe_cms_document` to clear the table for a fresh test run.

### Audit admin access
A security admin needs to check who has admin access in the current system. The admin asks to see all active accounts, and the agent calls `list_payload_users` to provide a clean list of identities.

### Verify content schema
A frontend dev wants to see the exact JSON structure of a 'User' object to map it to a component. The dev asks for the schema, and the agent uses `get_single_document` to show the exact structure.

## Benefits

- Skip the dashboard for repetitive tasks by using `create_cms_document` to push data. You can tell your agent to build out entire content sets from a JSON file in one go without manual entry.
- Update site-wide configurations instantly with `update_singleton_global` without manual edits. This lets you change global settings like site titles or maintenance flags immediately, ensuring your AI agent always has the most current data for your site.
- Clean up test data quickly using `wipe_cms_document` to keep your environment tidy. Instead of hunting for IDs in a dashboard, you can tell your agent to purge specific test nodes, keeping your production and staging environments clean.
- Find specific content items faster using `search_collection_where` query filters. Use natural language to find exactly what you need in a collection. Your agent can filter by status, date, or other criteria to pull specific data sets for you.
- Verify user permissions on the fly with `verify_token_identity` for security checks. Check the rules and permissions attached to any user account instantly. This helps you debug access issues and ensure your security settings are working as intended.
- Validate real data for frontend components using `get_singleton_global` to ensure accuracy. Stop guessing what the API will return. Have your agent pull the actual singleton data to verify that your frontend components are mapping the fields correctly.

## How It Works

The bottom line is you can manage your entire Payload CMS backend using natural language instead of manual dashboard clicks.

1. Input your Payload Base URL and Private API Token into the configuration.
2. Connect your AI client to the Vinkius marketplace.
3. Start asking your agent to perform tasks like creating documents or updating global settings.

## Frequently Asked Questions

**How can I use Payload CMS with an AI agent?**
You can connect the Payload CMS MCP to your AI client via the Vinkius marketplace. This gives your agent direct access to your CMS REST API so it can create, update, and query content for you.

**Can I update my website settings using the Payload CMS MCP?**
Yes, you can. The Connector includes tools to update global singleton settings, which allows your agent to change site-wide variables like titles, maintenance flags, or configuration values using natural language.

**Does Payload CMS MCP support deleting content?**
Yes, it does. You can instruct your agent to purge specific documents from your collections, which is helpful for cleaning up test data or removing old entries without using the dashboard.

**How do I manage users in Payload CMS with an AI?**
The Connector allows your agent to list all active admin identities and user accounts. You can ask the agent to show you who has access or check the specific permissions for a user.

**Can I create new blog posts via the Payload CMS MCP?**
Absolutely. You can provide the content details to your agent, and it will use the Connector to provision new documents in your blog collection, following your existing schema rules.

**Does this connect to my existing Payload CMS instance?**
Yes, it connects to your existing hosted or local instance. You just need to provide your Payload Base URL and your Private API Token in the configuration.

**Is it safe to update my database via the Payload CMS MCP?**
The Connector respects your existing API permissions and security settings. It only performs actions that your API token is authorized to do, ensuring your data stays secure.

**Can the Payload CMS MCP handle complex JSON updates?**
Yes, it is designed to handle JSON payloads. You can tell your agent to update specific blocks of data within a document, and it will handle the mutation via the REST API.

**Does this work with both MongoDB and Postgres implementations of Payload?**
Yes. The API agent interacts securely via Payload's standard abstracted REST endpoints. It remains explicitly agnostic of the underlying physical persistence arrays (Mongo/Postgres), resolving logically normalized JSON payloads.

**Can I query deeply nested values explicitly utilizing where limits?**
Absolutely. The `search_collection_where` capability leverages Payload's native query parser strings. You can send explicit nested filters like `title[equals]=Hello` limiting extraction loops flawlessly.

**What format do I need to send to patch or create a new CMS item?**
To command dynamic creations, pass the explicit stringified JSON properties directly mapping your specific Collection's local fields setup. The node forwards this strict data limit logically causing a DB insert over Payload endpoints.