# Payload Mcp

> MCP server that auto-generates tools from Payload CMS 3.0 type definitions so LLMs can produce up-to-date Payload code

- **Type:** MCP server
- **Install:** `agentstack add mcp-govcraft-payload-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Govcraft](https://agentstack.voostack.com/s/govcraft)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Govcraft](https://github.com/Govcraft)
- **Source:** https://github.com/Govcraft/payload-mcp

## Install

```sh
agentstack add mcp-govcraft-payload-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Payload MCP

A Model Context Protocol (MCP) server for Payload CMS 3.0 that auto-generates tools from Payload's TypeScript type definitions.

## Features

- Auto-generates MCP tools from Payload CMS 3.0 TypeScript definitions
- Provides an HTTP endpoint for LLMs to generate up-to-date Payload code
- Bridges the gap between LLM training cutoff and current Payload CMS API
- Supports all major Payload CMS features:
  - Collections
  - Globals
  - Fields
  - Authentication
  - Configuration

## How It Works

1. **Parse Type Definitions**: Uses ts-morph to analyze Payload's .d.ts files
2. **Generate Tools**: Converts types into MCP tools with parameters and code-gen logic
3. **Serve Endpoint**: Provides an /api/v1/payload-mcp endpoint for LLMs to query
4. **Generate Code**: Returns properly formatted Payload CMS 3.0 code

## Getting Started

### Prerequisites

- Node.js (v18 or higher)
- pnpm (v8 or higher)

### Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/payload-mcp.git
cd payload-mcp

# Install dependencies
pnpm install

# Generate tools from Payload CMS type definitions
pnpm generate-tools

# Start the development server
pnpm dev
```

### Usage

The MCP server exposes an endpoint at `/api/v1/payload-mcp` that accepts POST requests with the following structure:

```json
{
  "model": "claude-3-opus-20240229",
  "tools": [
    {
      "name": "createCollection",
      "parameters": {
        "slug": "posts",
        "fields": [
          {
            "name": "title",
            "type": "text",
            "required": true
          }
        ],
        "admin": {
          "useAsTitle": "title"
        }
      }
    }
  ]
}
```

The server will respond with generated Payload CMS 3.0 code:

```json
{
  "id": "uuid",
  "context": [
    {
      "id": "uuid",
      "data": {
        "code": "import { CollectionConfig } from 'payload/types';\n\nexport const postsCollection: CollectionConfig = {\n  slug: 'posts',\n  fields: [\n  {\n    \"name\": \"title\",\n    \"type\": \"text\",\n    \"required\": true\n  }\n],\n  // Add other properties as needed from params\n  ...{\n  \"admin\": {\n    \"useAsTitle\": \"title\"\n  }\n}\n};\n",
        "message": "Collection 'posts' created successfully"
      }
    }
  ],
  "tool_results": [
    {
      "tool_name": "createCollection",
      "output": {
        "code": "import { CollectionConfig } from 'payload/types';\n\nexport const postsCollection: CollectionConfig = {\n  slug: 'posts',\n  fields: [\n  {\n    \"name\": \"title\",\n    \"type\": \"text\",\n    \"required\": true\n  }\n],\n  // Add other properties as needed from params\n  ...{\n  \"admin\": {\n    \"useAsTitle\": \"title\"\n  }\n}\n};\n",
        "message": "Collection 'posts' created successfully"
      }
    }
  ]
}
```

## Available Tools

The following tools are auto-generated from Payload CMS 3.0 type definitions:

- **createCollection**: Creates a collection configuration
- **createGlobal**: Creates a global configuration
- **createField**: Creates a field configuration
- **createAuth**: Creates authentication configuration
- **createConfig**: Creates the main Payload CMS configuration

## Development

### Regenerating Tools

If you update Payload CMS or want to regenerate the tools:

```bash
# Update Payload
pnpm add payload@latest

# Regenerate tools
pnpm generate-tools
```

### Logging

The server uses Winston for logging. By default, logs are written to the `logs` directory with the following files:

- `combined.log`: All logs (info level and above)
- `error.log`: Error logs only
- `exceptions.log`: Uncaught exceptions
- `rejections.log`: Unhandled promise rejections

The server uses npm logging levels (from highest to lowest priority):
```
error: 0,
warn: 1,
info: 2,
http: 3,
verbose: 4,
debug: 5,
silly: 6
```

By default, the log level is set to `info`, which means only logs with level `info`, `warn`, and `error` will be recorded. To see more detailed logs:

- Set to `verbose` to see tool registration details
- Set to `debug` for even more detailed debugging information
- Set to `silly` for the most verbose output

You can change the log level by setting the `LOG_LEVEL` environment variable:

```bash
# Run with verbose logging (shows tool registration)
LOG_LEVEL=verbose pnpm start

# Run with debug logging (more detailed)
LOG_LEVEL=debug pnpm start

# Or set in .env file
# LOG_LEVEL=verbose
```

### Testing

To test the auto-generated tools:

```bash
# Start the server
pnpm dev

# In another terminal, run the test script
node test-generated-tools.mjs
```

## License

ISC
## Sponsor

Govcraft is a one-person shop—no corporate backing, no investors, just me building useful tools. If this project helps you, [sponsoring](https://github.com/sponsors/Govcraft) keeps the work going.

[](https://github.com/sponsors/Govcraft)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Govcraft](https://github.com/Govcraft)
- **Source:** [Govcraft/payload-mcp](https://github.com/Govcraft/payload-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-govcraft-payload-mcp
- Seller: https://agentstack.voostack.com/s/govcraft
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.