cloudflare / cloudflare/mcp-server-cloudflare
Document static API-token auth as a general option for MCP clients (works today, only documented for the OpenAI Responses API)
- Dominant language
- TypeScript
- Stars
- 4.2k
- Forks
- 514
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 2
Description
## Context
The hosted servers are reachable only through OAuth in most MCP clients, which makes the connection exactly as durable as the client's token store. In Claude Code the MCP OAuth grants are kept inside the same macOS Keychain item as the Claude account credential, so logging out of Claude — or switching Claude accounts — discards them. Today (2026-08-30) that cost me six browser re-authorizations, one per Cloudflare server (`api`, `bindings`, `observability`, `ai-gateway`, `auditlogs`, `graphql`), none of which had actually expired on your side. I have filed that half upstream with Anthropic as anthropics/claude-code#90647.
While looking for a way to make the connection survive a client-side credential reset, I found that a plain Cloudflare API token already works as a bearer credential — but the README only mentions API tokens under "Using Cloudflare's MCP servers from the OpenAI Responses API", so it reads as an OpenAI-specific path rather than something any MCP client can use.
## What I measured (2026-08-30)
```
# initialize, with a Cloudflare API token as bearer
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://mcp.cloudflare.com/mcp \
-H "Authorization: Bearer $CF_API_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-H 'MCP-Protocol-Version: 2025-06-18' \
--data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0.1"}}}'
200
```
- Same request with the `Authorization` header removed: `401`.
- `tools/list` with the token: `200`, returns `docs`, `search`, `execute`.
- `https://observability.mcp.cloudflare.com/mcp` behaves the same way (`200`, `serverInfo: workers-observability 0.5.5`).
So static-token auth is implemented across the hosted servers, it is just not documented as a general option.
## Request
1. Document bearer API-token auth in "Connect to an MCP server" as a supported alternative to OAuth for any MCP client, not only the OpenAI Responses API — including the header form clients actually write, e.g. in Claude Code's `.mcp.json`:
```json
{
"mcpServers": {
"cloudflare-api": {
"type": "http",
"url": "https://mcp.cloudflare.com/mcp",
"headers": { "Authorization": "Bearer ${CLOUDFLARE_API_TOKEN}" }
}
}
}
```
2. State the support guarantee. Is this a first-class auth path, or an implementation detail that may disappear? Anyone moving their configuration off OAuth needs that answer before doing it.
3. While documenting it, list the token scopes each server needs — this is the same gap already reported in #307.
4. Optional, and separate from the above: for the OAuth path, support silent re-authorization for a client that the user has already consented to, so a client-side token loss costs one redirect rather than a full consent click per server.
## Why this matters
An OAuth-only path means any client-side credential reset — an account switch, a reinstall, a corrupted token store — costs one browser round trip per server, and it scales with the number of servers a user has configured. A documented static-token option makes the connection survive that, and it is the only workable path for headless and CI clients that cannot open a browser at all.
Contributor guide
Research direction
Start with the README's "Connect to an MCP server" section and compare it with the existing OpenAI Responses API token guidance. Verify the bearer-header example against the documented MCP endpoints and review #307 for the missing per-server token scopes. Done means the README explains the general API-token option, its support guarantee, and required scopes, while keeping OAuth re-authorization separate.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, authentication, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100