feat: support custom header

[popomore]

Summary

This PR adds custom header support to the MCP Inspector, allowing users to configure and send custom HTTP headers when connecting to MCP servers. This enhancement improves flexibility for testing servers that require authentication tokens, API keys, or other custom headers.

Ref #249

Motivation and Context

Many MCP servers require custom headers for authentication (e.g., Bearer tokens, API keys) or other configuration purposes. The current inspector lacks the ability to set these headers, making it difficult to test servers that have authentication requirements or need specific header configurations.
This feature addresses the need to:

• Test MCP servers with authentication requirements
• Send custom configuration headers
• Provide a more complete testing environment for real-world MCP server scenarios

Changes Made

• Added custom header configuration UI components
• Implemented header management functionality in the connection logic
• Added TypeScript type definitions for custom headers
• Created tests for the new header functionality
• Updated the server connection logic to include custom headers
• Enhanced the inspector interface to support header input and management

How Has This Been Tested?

• Tested custom header input and validation in the UI
• Verified headers are properly sent with MCP server connections
• Tested with authentication headers (Bearer tokens, API keys)
• Confirmed backward compatibility with existing connections
• Validated error handling for invalid header formats
• Tested header persistence and management functionality

Breaking Changes

No breaking changes - this is a backward-compatible feature addition

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

UI

[wickhu]

LGTM

[ZZZZ-WINK]

LGTM

[olaservo]

Hi, this older PR is editing a lot of the same UI, so before we move forward with this one, lets wait on this PR to be finalized: #345

If we feel this is urgent and is blocked for too long, we can revisit how to best coordinate these. Thanks for your patience!

[cliffhall]

In the meantime, I don't love the hash in the # Headers accordion pleat. Or the Custom Headers field being a small text field with JSON contents. that would be difficult and error prone to edit. If it just contains the object that represetns all the custom header entries, it seems redundant.

[olaservo]

Hi @popomore , it seems like the main outstanding concern we had here was with the UX (see Cliff's comment above). In general I think we might need to revisit the UI design of the sidebar since there is a lot going on there and editing long values can be annoying. Any thoughts on how we might tweak this to address the callouts above? Thanks!

[PederHP]

Suggestion: rename "custom headers" to "additional headers" which is the term used in the SDKs. Also headers can be used for other purposes than authentication, so I suggest changing the comments to be less categorical about the purpose of the headers. For example, I have seen them used for localization purposes.

[popomore]

@cliffhall @olaservo I’m not sure whether using a custom header field or a hash is the better approach — I tend to prefer using a hash for this purpose.

@PederHP I agree with the use of additional headers.

I’ll make the changes after the requirements are confirmed.

[cliffhall]

@cliffhall @olaservo I’m not sure whether using a custom header field or a hash is the better approach — I tend to prefer using a hash for this purpose.

I don't see the functionality of "#" in the button name, and I still question the need for the Custom (or Additional) headers field that has the big JSON ball inside it. Will you be editing that separately somewhere and pasting it in? Surely you don't expect the user to edit JSON inside it? If it just accumulates the headers that are created in the forms below in a read only way, what would you be doing with the resultant content? Copying it and pasting it? Where and for what? We have very little real estate in the sidebar, and this field seems unnecessary.

I suggest the button that has "# Headers" be called "Additional Headers" and it open or close the section with "Header 1", "Header 2" boxes etc. Those boxes should be in a vertical box that scrolls on its own if the whole sidebar becomes filled, as it easily could if you add a lot of headers. That should be the extent of the UI unless there is some demonstrable need for the JSON field.

[JadJabbour]

when this?

[cliffhall]

@popomore Any thoughts on my last comment, and whether you'd like to carry on with this PR?

[kosukekurimoto]

I think this feature is really good.

[peterswimm]

Fills a real gap: Setting headers is critical for testing servers with auth or special config. This makes the inspector much more practical for real-world scenarios .
• End-to-end implementation: UI, config, client, and server are all updated consistently .
• Good test coverage: Add/update/remove flows are all covered, including multiple headers .
• Backward compatible: No breaking changes; users can ignore the feature if not needed .
• Secrets awareness: Values are masked in the UI with type="password" .
• Extensible design: Prefixing with x-mcp-custom-* avoids collisions and makes client-supplied headers explicit .

⸻

Suggested improvements
1. Terminology and UX
• Rename “Headers” → “Additional headers” to match SDK language.
• Remove the # hash icon/label.
• Make the section itself scrollable so the sidebar does not overflow if many headers are present.
2. Config shape and validation
• Store headers as a typed array in InspectorConfig, not a raw JSON string.
• Replace silent catch{} parsing with schema validation (e.g., zod) and show user errors when invalid.
3. Security and privacy
• Treat values as secrets everywhere. Ensure copy/export features omit MCP_CUSTOM_HEADERS.
• Add server-side blocklist: disallow forwarding hop-by-hop and sensitive headers (host, connection, content-length, transfer-encoding, upgrade, sec-websocket-, proxy-, authorization if bearer already set).
• Consider per-server scoping so keys are not sent to the wrong origin.
4. Name handling
• Preserve original header case for user clarity. Normalize only at send time.
5. Precedence rules
• Define and test behavior when both bearer/OAuth and custom Authorization are present.
6. Multiple values and validation
• Trim names/values. Reject empty names and duplicates.
• Consider supporting multi-value headers. Add tests for parse errors and de-dupe.
7. Docs
• Extend docs with examples beyond auth (e.g. X-Locale: fr-FR).
• Note security caveats and explain server blocklist behavior.

[cliffhall]

@peterswimm I think this PR has been abandoned. But there is another PR in the queue that looks better IMO.