Skip to content

docs(mcp): troubleshoot Cloudflare blocking self-hosted MCP connections - #9554

Open
BhagyaAmarasinghe wants to merge 1 commit into
mainfrom
bhagya/cloudflare-mcp-protection-block-0e19b0
Open

docs(mcp): troubleshoot Cloudflare blocking self-hosted MCP connections#9554
BhagyaAmarasinghe wants to merge 1 commit into
mainfrom
bhagya/cloudflare-mcp-protection-block-0e19b0

Conversation

@BhagyaAmarasinghe

@BhagyaAmarasinghe BhagyaAmarasinghe commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Fixes ENG-2221

What & why

Was: a self-hosted instance behind Cloudflare could fail to connect to ChatGPT or claude.ai with what looked like an OAuth error, and the docs never mentioned Cloudflare.

Now: the MCP setup guide explains why the browser works while the client fails, and which Cloudflare settings to change without disabling protection site-wide.

  • Also covers Formbricks' own signing-key fetch, which a Cloudflare challenge turns into a 401 on every tool call.

Where to look

  • setup.mdx:210 — Cloudflare menu paths and the list of paths clients call

Breaking changes

  • This PR contains breaking changes

None. Docs only.

Migrations & env

  • none

How this was tested

Rerun: none — docs only, no executable change.

Coverage

Behaviour How Outcome
Cloudflare settings match Cloudflare's current docs manual AI bot policies path and categories confirmed; Bot Fight Mode can't be skipped, Super Bot Fight Mode can
Listed paths are the ones clients call without a browser manual Matched to the .well-known routes, /api/auth/oauth2/* and /api/mcp on main
Key-fetch failure symptom manual modules/mcp/auth.ts returns 401 and logs failureSource: "jwks_fetch"

Open gaps

  • Not reproduced on a real Cloudflare zone; the before/after is the reporter's (GitHub issue 8742), who couldn't tell block from challenge.
  • Rendering not checked: Mintlify skips PR previews; the list-in-accordion markup follows keycloak-oidc.mdx.
  • ChatGPT end to end is still unverified on staging (open gap carried over from fix(auth): let claude.ai and ChatGPT MCP connectors register through DCR #9494).

Risks

  • Cloudflare renames dashboard menus often, so the paths may drift.

Note

AI model used — claude-opus-5-5, reasoning effort xhigh.

🤖 Generated with Claude Code

@BhagyaAmarasinghe @claude
docs(mcp): troubleshoot Cloudflare blocking self-hosted MCP connections
1579edf 
Add a setup-guide troubleshooting entry for self-hosted instances behind
Cloudflare: AI bot policies (Agent), Bot Fight Mode vs Super Bot Fight Mode,
WAF rules and Access, the paths MCP clients call without a browser, and the
JWKS fetch that a Cloudflare challenge turns into 401s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@BhagyaAmarasinghe
BhagyaAmarasinghe requested a review from a team as a code owner October 7, 2026 16:28
@BhagyaAmarasinghe
BhagyaAmarasinghe requested review from Dhruwang and removed request for a team October 7, 2026 16:28
@coderabbitai

coderabbitai Bot commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository: formbricks/formbricks/.coderabbit.yaml
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: 60c1b820-636c-43ce-a7bd-76526b5dbcb3
📥 Commits

Reviewing files that changed from the base of the PR and between 794f5a4 and 1579edf.

📒 Files selected for processing (1)
  • docs/platform/mcp/setup.mdx

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

Walkthrough

Adds troubleshooting guidance for self-hosted MCP servers behind Cloudflare. It identifies relevant requests, paths, and Cloudflare settings. It also documents the 401 response and jwks_fetch failure source associated with a challenged public JWKS fetch, and points to MCP_OAUTH_JWKS_URL as an internal endpoint override.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 1579e

The troubleshooting guidance is ready to merge after normal documentation checks; the Cloudflare dashboard paths and page rendering remain unverified.

🚥 Pre-merge checks | ✅ 7
✅ Passed checks (7 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Breaking Changes Match The Diff ✅ Passed The PR description leaves - [ ] This PR contains breaking changes unticked. The authoritative diff changes only docs/platform/mcp/setup.mdx and adds a troubleshooting accordion. It does not change…
Only The Ticket Line Carries A Magic Word ✅ Passed PASS — The description contains one magic-word pair, “Fixes ENG-2221,” on the ticket line at the top. The later reference “#9494” has no magic word next to it, and no other Fixes, Closes, `Resolve…
Coverage Accounts For The Whole Diff ✅ Passed PASS — The authoritative PR diff changes only docs/platform/mcp/setup.mdx; it introduces no product behavior or executable code. The description explicitly states “docs only, no executable change,” …
Title check ✅ Passed The title uses the required Conventional Commits format, uses the allowed docs type and mcp scope, describes the documentation change, and has a lowercase summary without a trailing period.
Description check ✅ Passed The description follows the repository template and documents the change, affected paths, breaking-change status, migrations, testing coverage, open gaps, risks, and AI tool details. It is sufficientl…
  • Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sonarqubecloud

sonarqubecloud Bot commented Oct 7, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Dhruwang Dhruwang Awaiting requested review from Dhruwang Dhruwang is a code owner automatically assigned from formbricks/engineering

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@BhagyaAmarasinghe