docs: add server-side dynamic header injection recipe and tip for MCP header forwarding

[Pratham-Mishra04]

Summary

Documents how to inject dynamic, server-side headers into outgoing MCP requests from a PreMCPHook plugin, covering use cases that static configuration cannot address (e.g., per-user identity headers, short-lived service tokens, per-request correlation IDs).

Changes

• Added a tip to the header forwarding section in connecting-to-servers.mdx clarifying that forwarded headers come from the caller and are untrusted, and pointing readers to the new plugin recipe for server-side injection.
• Added a new "Recipe: injecting dynamic headers server-side" section to writing-go-plugin.mdx (v1.5.x+) with a full PreMCPHook code example that merges plugin-injected headers into BifrostContextKeyMCPExtraHeaders, along with notes on the per-client allowlist, transport compatibility (HTTP/SSE only), and why Connect hooks are the wrong place for per-request identity.

Type of change

• Bug fix
• Feature
• Refactor
• Documentation
• Chore/CI

Affected areas

• Core (Go)
• Transports (HTTP)
• Providers/Integrations
• Plugins
• UI (React)
• Docs

How to test

Review the rendered documentation to confirm:

• The tip in connecting-to-servers.mdx links correctly to the new recipe anchor in writing-go-plugin.mdx.
• The code example in the recipe compiles without errors when dropped into a plugin project.
• The <Note> and key-points list render correctly in the docs site.

Screenshots/Recordings

N/A

Breaking changes

• Yes
• No

Related issues

N/A

Security considerations

The added documentation explicitly calls out that caller-forwarded headers must be treated as untrusted input by upstream servers, and that plugin-injected identity headers (e.g., signed-in user email) are the appropriate mechanism when the caller must not control the value. The per-client allowed_extra_headers allowlist is noted as the enforcement boundary for both forwarded and plugin-injected headers.

Checklist

• I read docs/contributing/README.md and followed the guidelines
• I added/updated tests where appropriate
• I updated documentation where needed
• I verified builds succeed (Go and UI)
• I verified the CI pipeline passes locally if applicable

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Pratham-Mishra04]

• docs: add server-side dynamic header injection recipe and tip for MCP header forwarding #5476 👈 (View in Graphite)
• dev

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c1c15d59-4d07-4b4f-a953-23027dd5bbc0

📥 Commits

Reviewing files that changed from the base of the PR and between f15fe52 and 9eabe51.

📒 Files selected for processing (2)

• docs/mcp/connecting-to-servers.mdx
• docs/plugins/writing-go-plugin.mdx

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/mcp/connecting-to-servers.mdx
• docs/plugins/writing-go-plugin.mdx

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Clarified trust boundaries for headers forwarded to MCP servers, distinguishing untrusted caller headers from non-spoofable plugin-injected headers.
  • Added an MCP recipe for injecting dynamic, per-request headers in Go plugins.
  • Documented that injected headers apply only to HTTP/SSE, respect each client’s allowed_extra_headers allowlist, and explains why connect-time hooks aren’t suitable.
  • Included a complete example using computed user information.

Walkthrough

Documentation clarifies MCP forwarded-header trust boundaries and adds a Go recipe for injecting per-request headers through PreMCPHook, including allowlist, transport, and Enterprise-specific behavior.

Changes

MCP header documentation

Layer / File(s)	Summary
MCP header trust and injection guidance docs/mcp/connecting-to-servers.mdx, docs/plugins/writing-go-plugin.mdx	Documents trust boundaries and allowlist enforcement for forwarded and plugin-injected headers, and adds a PreMCPHook example for dynamic HTTP/SSE header injection.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested reviewers: akshaydeo, danpiths

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main documentation changes about dynamic header injection and MCP header forwarding.
Description check	✅ Passed	The description follows the template and covers summary, changes, type, affected areas, testing, security, and checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 07-23-docs_add_plugin_recipe_for_server-side_dynamic_mcp_header_injection

---

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

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/mcp/connecting-to-servers.mdx`:
- Line 481: Update the forwarding tip in docs/mcp/connecting-to-servers.mdx at
lines 481-481 to warn that all extra header values may be attached to spans and
exported to Datadog regardless of content-redaction settings. Update the
email-header example in docs/plugins/writing-go-plugin.mdx at lines 825-856 to
explicitly warn that trace or Datadog header capture can expose this PII.

In `@docs/plugins/writing-go-plugin.mdx`:
- Line 862: Reword the bullet in the Connect hooks guidance to remove the claim
that no per-request identity exists at Connect time. Explain instead that
Connect runs once per shared transport and therefore cannot safely stamp
identity that varies across later callers, while directing per-request identity
to the envelope hooks.
- Around line 825-849: Update PreMCPHook to inject X-User-Email only when
req.ClientName matches the intended MCP client or server; return unchanged for
other clients, including wildcard-configured clients. If client filtering cannot
be shown in the sample, explicitly warn that the hook must restrict destinations
when multiple MCP servers are configured.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 330a7972-2c8e-4e36-a2ac-5525b2724bea

📥 Commits

Reviewing files that changed from the base of the PR and between 9c3e4c7 and f15fe52.

📒 Files selected for processing (2)

• docs/mcp/connecting-to-servers.mdx
• docs/plugins/writing-go-plugin.mdx

[Pratham-Mishra04]

Merge activity

• Jul 22, 7:55 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jul 22, 7:56 PM UTC: @Pratham-Mishra04 merged this pull request with Graphite.