Allow add extra headers for remote server connection

[ShenghaiWang]

Allow add extra headers for remote server connection like bearer token

Motivation and Context

Many MCP servers require authentication via a bearer token. By allowing clients to specify custom header values, this approach supports bearer token authentication and provides flexibility for servers that require additional or specialized headers.

How Has This Been Tested?

Yes. I can use this to connect to GitHub MCP server by adding bearer token.

Breaking Changes

No. The newly added header parameter has default empty value.

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

[mattt]

Hi @ShenghaiWang. Sorry for not responding sooner.

I think it's important to distinguish two separate concerns here:

1. Injecting credentials
2. Setting any other HTTP headers

For pretty much everything other than auth, we can use the existing httpAdditionalHeaders property of URLSession.

The URL Loading System has a whole process for handling authentication challenges. Unfortunately, it's hard to use, and out of step with how APIs have worked since OAuth 2. So many (most?) developers just set headers directly on requests instead of bothering with it.

The one downside of hardcoding credentials in the initializer is that you can't refresh them within the same session. So I think a better pattern would be to have the initializer accept a closure that lets the caller customize a request before it goes out:

public init(
  endpoint: URL,
  configuration: URLSessionConfiguration = .default,
  requestModifier: (URLRequest) -> URLRequest = { _ in },
  // ...
)

Would something like that approach work for your use case?

[ShenghaiWang]

Thanks @mattt . You’re absolutely right—using ‎httpAdditionalHeaders covers most header values, and handling authentication through the delegate is effective as well. I also like the idea of a ‎requestModifier, which gives callers flexibility to customize the URLSession.

From an SDK perspective, I think it’s best to offer all these options and let users decide which approach suits their needs, as long as including them doesn’t negatively impact the SDK’s codebase.

[mattt]

@ShenghaiWang Thanks again for your help with this. I just merged #152, which implements the approach we discussed. I'm cutting a new (minor) release now, which will include that change.