Add support for custom headers in HostedMcpServerTool #7053
Conversation
Introduces a Headers property to HostedMcpServerTool for specifying additional request headers. Updates OpenAIResponsesChatClient to pass these headers when creating MCP tools and adds unit tests to verify header roundtripping.
There was a problem hiding this comment.
Pull Request Overview
This PR adds support for custom HTTP headers in HostedMcpServerTool, enabling users to specify additional request headers when communicating with remote MCP servers.
- Introduces a
Headersproperty of typeIDictionary<string, string>?to theHostedMcpServerToolclass - Updates
OpenAIResponsesChatClientto pass these headers to both variants ofResponseTool.CreateMcpTool() - Adds roundtrip tests to verify the Headers property can be set, retrieved, and cleared
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| src/Libraries/Microsoft.Extensions.AI.Abstractions/Tools/HostedMcpServerTool.cs | Adds the nullable Headers property with XML documentation |
| src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIResponsesChatClient.cs | Passes mcpTool.Headers parameter to both CreateMcpTool overloads (URI-based and connector ID-based) |
| test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Tools/HostedMcpServerToolTests.cs | Adds assertions to verify Headers can be set to a dictionary, retrieved, and reset to null |
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Tools/HostedMcpServerToolTests.cs
Show resolved
Hide resolved
|
@stephentoub any chance I can get an assignee on this one to help with getting it through? This is #7049 with the reverts. |
|
Thanks for your PR @echapmanFromBunnings. We originally pursued this API shape because OpenAI supported headers in the request, while Anthropic only supported passing an auth token. I initially took the broader approach and used a dictionary in Later, OpenAI added support for passing the token in the same way Anthropic does, which suggested to me that there might not be many use cases for headers beyond auth and that we don't need a headers dictionary in the class. For the sake of doing an informed decision, could you share more about what kinds of headers you need to pass to your MCP server? If we bring the headers dictionary back, we need to reconsider if we want to keep |
|
Hi @jozkee Since the MCP server essentially operates as an HTTP client, couldn’t we simply allow these headers to leverage the underlying protocol? In this context, headers are not being used for authentication, so encountering a header should not imply it is solely for that purpose. These are two distinct concerns and should be treated as such. |
| public HostedMcpServerToolApprovalMode? ApprovalMode { get; set; } | ||
|
|
||
| /// <summary> | ||
| /// Gets or sets additional headers to include in requests to the remote MCP server. |
There was a problem hiding this comment.
From the previous version of this:
| /// Gets or sets additional headers to include in requests to the remote MCP server. | |
| /// Gets or sets the HTTP headers that the AI service should use when calling the remote MCP server. |
There was a problem hiding this comment.
Do we want to add <remarks> mentioning that some providers may return an error if both AuthorizationToken and an "authorization" header are specified? This is the case for OpenAI.
$ curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "gpt-4o-mini",
"tools": [
{
"type": "mcp",
"server_label": "gh",
"server_url": "https://api.githubcopilot.com/mcp",
"authorization": "github_pat_123",
"headers": { "Authorization": "Bearer github_pat_123" }
}
],
"input": "What tools are available?"
}'{
"error": {
"message": "Cannot specify both 'authorization' parameter and 'Authorization' header.",
"type": "invalid_request_error",
"param": "headers",
"code": null
}
}
| url, | ||
| mcpTool.AuthorizationToken, | ||
| mcpTool.ServerDescription) : | ||
| mcpTool.ServerDescription, mcpTool.Headers) : |
There was a problem hiding this comment.
| mcpTool.ServerDescription, mcpTool.Headers) : | |
| mcpTool.ServerDescription, | |
| mcpTool.Headers) : |
| new McpToolConnectorId(mcpTool.ServerAddress), | ||
| mcpTool.AuthorizationToken, | ||
| mcpTool.ServerDescription); | ||
| mcpTool.ServerDescription, mcpTool.Headers); |
There was a problem hiding this comment.
| mcpTool.ServerDescription, mcpTool.Headers); | |
| mcpTool.ServerDescription, | |
| mcpTool.Headers); |
|
CI errors are about CompatibilitySuppression.xml since we are bringing the property back. I suspect we need to remove them from: cc @joperezr |
Deleted baseline suppressions for the Headers property and its setter in HostedMcpServerTool from CompatibilitySuppressions.xml.
Expanded XML documentation for the Headers property in HostedMcpServerTool to clarify usage and behavior. Minor formatting adjustments in OpenAIResponsesChatClient for MCP tool creation calls.
|
Addressed all PR comments, and added extensive documents on that headers prop @jozkee |
Deleted baseline suppressions for get_Headers and set_Headers members of HostedMcpServerTool across net8.0, net9.0, and netstandard2.0. This likely reflects removal or resolution of related compatibility issues.
…manFromBunnings/extensions into AddHeaderToMcpToolCreation
2 participants
Introduces a Headers property to HostedMcpServerTool for specifying additional request headers. Updates OpenAIResponsesChatClient to pass these headers when creating MCP tools and adds unit tests to verify header roundtripping.
Microsoft Reviewers: Open in CodeFlow