Skip to content

docs(plugin-mcp): clarify Bearer-only auth on /api/mcp endpoint#16602

Open
algojogacor wants to merge 1 commit into
payloadcms:mainfrom
algojogacor:fix/plugin-mcp-bearer-auth-docs
Open

docs(plugin-mcp): clarify Bearer-only auth on /api/mcp endpoint#16602
algojogacor wants to merge 1 commit into
payloadcms:mainfrom
algojogacor:fix/plugin-mcp-bearer-auth-docs

Conversation

@algojogacor
Copy link
Copy Markdown

What?

Adds a <Banner type="info"> to the MCP plugin documentation clarifying that the /api/mcp endpoint only supports Authorization: Bearer <key> authentication. Unlike other Payload API-key-based endpoints that accept the <collection-slug> API-Key <key> convention, the MCP endpoint will reject any other auth scheme.

Why?

Fixes #16572

Users familiar with Payload's standard API-Key auth convention (used by every other API-key-backed surface) naturally try payload-mcp-api-keys API-Key <token> against /api/mcp. This is silently rejected. The existing docs mention Bearer but don't call out that it's the only supported format.

How?

Added a <Banner type="info"> block after the "All MCP requests must include a valid API key as a Bearer token" sentence in docs/plugins/mcp.mdx, explicitly stating:

  • The MCP endpoint only supports Authorization: Bearer <key>
  • The payload-mcp-api-keys API-Key <key> convention used elsewhere in Payload does not work here

Changes

  • docs/plugins/mcp.mdx: Added Banner note about Bearer-only auth (+11 -1 lines)

Testing

  • Existing Bearer examples: All curl/config examples in the docs remain unchanged and correct ✅
  • New Banner renders correctly: The <Banner type="info"> shortcode is already used elsewhere in the same file (lines 13, 126, 187) ✅
  • Clarity improvement: A reader who jumps to the "How Access Control Works" section looking for auth format will now see the explicit clarification ✅

Unlike other Payload API-key-based endpoints that accept the
<collection-slug> API-Key <key> convention, the MCP endpoint only
supports Authorization: Bearer <key>. Add Banner clarifying this.

Fixes payloadcms#16572
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant