Open
Conversation
Adds @payloadcms/plugin-mcp to enable MCP server access to the local Payload CMS database, useful for exploring content structures during development. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pin mcp-handler to 1.0.7 via pnpm overrides to work around a bug in @payloadcms/plugin-mcp@3.78.0 where handler(request) expects a return value but mcp-handler returns a (req, res) callback. Also exclude payload-mcp-api-keys from TenantScopedCollectionWithHash in upsert.ts since the MCP API key collection lacks tenant/contentHash fields. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Extend the @payloadcms/plugin-mcp patch to pass the `instructions` field through to the underlying MCP SDK. Configure serverInfo and instructions in the plugin to describe the multi-tenant data model and common query patterns to MCP clients. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Configure avyweb-payload-local (localhost:3000) and avyweb-payload-prod (avy-fx.org) MCP servers in .mcp.json with env var placeholders for API keys. Set AVYWEB_MCP_API_KEY_LOCAL and AVYWEB_MCP_API_KEY_PROD in your environment to authenticate. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add setup instructions, when to use/not use guidance, and querying tips for the avyweb-payload-local and avyweb-payload-prod MCP servers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Replace individual denied-role tests with a parameterized loop over all non-super-admin roles: providerManager, multiTenantAdmin, singleTenantAdmin, singleTenantForecaster, singleTenantStaff, providerUser, multiProviderUser. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…nges Document the read-only-by-configuration design, custom tools extensibility, .mcp.json setup, server instructions feature, and the combined patch for authDepth and instructions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…on and isUser guards Revert addRandomSuffix and zod bump (unrelated to MCP feature). Tighten E2E denied-role assertion by removing weak hasNoCreateButton fallback. Remove dangling upstream PR doc reference. Add isUser type guards to hasProviderAccess and globalRoleAssignmentsForUser to handle the new PayloadMcpApiKey auth collection type. Generate migration for payload_mcp_api_keys table. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Introduces getUser(req) that extracts a User from the request, returning null if unauthenticated or authenticated as a different collection type (e.g., PayloadMcpApiKey). Replaces the awkward `!user || !isUser(user)` pattern at 8 call sites. The bare isUser() type guard remains for the 3 sites that receive user as a standalone argument from Payload callbacks. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
Migration Safety CheckFound 3 potential issues: 20260403_204010.ts Warning (line 32): DELETE keyword detected - review for data loss FOREIGN KEY (\`user_id\`) REFERENCES \`users\`(\`id\`) ON UPDATE no action ON DELETE set nullWarning (line 45): ALTER keyword detected - review for data loss sql`ALTER TABLE \`payload_locked_documents_rels\` ADD \`payload_mcp_api_keys_id\` integer REFERENCES payload_mcp_api_keys(id);`,Warning (line 51): ALTER keyword detected - review for data loss sql`ALTER TABLE \`payload_preferences_rels\` ADD \`payload_mcp_api_keys_id\` integer REFERENCES payload_mcp_api_keys(id);`,Review these patterns and add backup/restore logic if needed. See |
Contributor
|
Preview deployment: https://mcp-server.preview.avy-fx.org |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Integrates the Payload MCP plugin (
@payloadcms/plugin-mcp) to expose a Model Context Protocol server at/api/mcp. This allows AI tools like Claude Code to query CMS content directly using API key authentication, with full RBAC enforcement.It has been configured to only allow read access to collections and to only allow super admins to manage API keys.
Related Issues
None
Key Changes
src/plugins/index.ts): ConfiguresmcpPluginwith read-only access to 16 collections and thenacWidgetsConfigglobal. Includes server instructions that describe the multi-tenant data model and common query patterns to MCP clients.@payloadcms/plugin-mcp(patches/@payloadcms__plugin-mcp.patch): Adds two features not yet upstream:authDepth— controls population depth when authenticating API key users (our RBAC needs depth 3 to resolveglobalRoleAssignments.docs[].globalRole.rules)instructions— passes the MCP protocol's instructions field through to clients during initializationisUsertype guard andgetUserhelper (src/utilities/isUser.ts): The MCP plugin adds a second auth collection (payload-mcp-api-keys), which widensreq.userto a union type. These utilities let existing code safely narrow back toUserwithout type assertions. We can't narrow this at the Payload config level - this is a result of having multiple "auth" collections.hasSuperAdminPermissionson all CRUD operations.__tests__/e2e/admin/collections/mcp-api-keys.e2e.spec.ts): Tests that super admin can access the MCP API Keys collection and all other roles (7 roles) are denied.src/migrations/20260403_204010.ts): Adds thepayload_mcp_api_keystable and related schema.docs/mcp-server.md,CLAUDE.md): Setup guide, security model, troubleshooting, and MCP querying tips for developers.How to test
pnpm installto apply the patchpnpm seedto set up the database with the new migrationpnpm devto start the dev serverdocs/mcp-server.mdfindTenants,findPosts) - ask something like "List the posts for NWAC"Screenshots / Demo video
https://www.loom.com/share/ed05450621d9421baf0a5b356bd467a5
Migration Explanation
Adds the
payload_mcp_api_keystable with columns for API key management (label, user relationship, API key hash, enabled collections, etc.). This is a purely additive migration — no existing tables are modified.Future enhancements / Questions
@payloadcms/plugin-mcpfor theauthDepthandinstructionsfeatures to eliminate the patchcreateonposts) for AI-assisted content workflows