Skip to content

feat: add support for custom HTTP headers in client requests #546

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Oct 21, 2025
Merged

feat: add support for custom HTTP headers in client requests #546

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
5a8cd65
feat: add support for custom HTTP headers in client requests
matthisholleville Aug 13, 2025
5c850ff
Merge branch 'main' into feat/custom-http-headers
matthisholleville Sep 29, 2025
8eaa504
feat(client/transport): enhance HTTP request flexibility
matthisholleville Oct 2, 2025
660ac1a
fix: Improve OAuth error handling and test readability in HTTP transport
matthisholleville Oct 21, 2025
99ccc6e
fix: improve variable naming for clarity in streamable_http_test
matthisholleville Oct 21, 2025
01c3345
feat: Ensure system headers are preserved in streamable HTTP tests
matthisholleville Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 13 additions & 10 deletions client/client.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"fmt"
"net/http"
"slices"
"sync"
"sync/atomic"
Expand Down Expand Up @@ -130,6 +131,7 @@ func (c *Client) sendRequest(
ctx context.Context,
method string,
params any,
header http.Header,
) (*json.RawMessage, error) {
if !c.initialized && method != "initialize" {
return nil, fmt.Errorf("client not initialized")
Expand All @@ -142,6 +144,7 @@ func (c *Client) sendRequest(
ID: mcp.NewRequestId(id),
Method: method,
Params: params,
Header: header,
}

response, err := c.transport.SendRequest(ctx, request)
Expand Down Expand Up @@ -179,7 +182,7 @@ func (c *Client) Initialize(
Capabilities: capabilities,
}

response, err := c.sendRequest(ctx, "initialize", params)
response, err := c.sendRequest(ctx, "initialize", params, request.Header)
if err != nil {
return nil, err
}
Expand Down Expand Up @@ -224,7 +227,7 @@ func (c *Client) Initialize(
}

func (c *Client) Ping(ctx context.Context) error {
_, err := c.sendRequest(ctx, "ping", nil)
_, err := c.sendRequest(ctx, "ping", nil, nil)
return err
}

Expand Down Expand Up @@ -305,7 +308,7 @@ func (c *Client) ReadResource(
ctx context.Context,
request mcp.ReadResourceRequest,
) (*mcp.ReadResourceResult, error) {
response, err := c.sendRequest(ctx, "resources/read", request.Params)
response, err := c.sendRequest(ctx, "resources/read", request.Params, request.Header)
if err != nil {
return nil, err
}
Expand All @@ -317,15 +320,15 @@ func (c *Client) Subscribe(
ctx context.Context,
request mcp.SubscribeRequest,
) error {
_, err := c.sendRequest(ctx, "resources/subscribe", request.Params)
_, err := c.sendRequest(ctx, "resources/subscribe", request.Params, request.Header)
return err
}

func (c *Client) Unsubscribe(
ctx context.Context,
request mcp.UnsubscribeRequest,
) error {
_, err := c.sendRequest(ctx, "resources/unsubscribe", request.Params)
_, err := c.sendRequest(ctx, "resources/unsubscribe", request.Params, request.Header)
return err
}

Expand Down Expand Up @@ -369,7 +372,7 @@ func (c *Client) GetPrompt(
ctx context.Context,
request mcp.GetPromptRequest,
) (*mcp.GetPromptResult, error) {
response, err := c.sendRequest(ctx, "prompts/get", request.Params)
response, err := c.sendRequest(ctx, "prompts/get", request.Params, request.Header)
if err != nil {
return nil, err
}
Expand Down Expand Up @@ -417,7 +420,7 @@ func (c *Client) CallTool(
ctx context.Context,
request mcp.CallToolRequest,
) (*mcp.CallToolResult, error) {
response, err := c.sendRequest(ctx, "tools/call", request.Params)
response, err := c.sendRequest(ctx, "tools/call", request.Params, request.Header)
if err != nil {
return nil, err
}
Expand All @@ -429,15 +432,15 @@ func (c *Client) SetLevel(
ctx context.Context,
request mcp.SetLevelRequest,
) error {
_, err := c.sendRequest(ctx, "logging/setLevel", request.Params)
_, err := c.sendRequest(ctx, "logging/setLevel", request.Params, request.Header)
return err
}

func (c *Client) Complete(
ctx context.Context,
request mcp.CompleteRequest,
) (*mcp.CompleteResult, error) {
response, err := c.sendRequest(ctx, "completion/complete", request.Params)
response, err := c.sendRequest(ctx, "completion/complete", request.Params, request.Header)
if err != nil {
return nil, err
}
Expand Down Expand Up @@ -514,7 +517,7 @@ func listByPage[T any](
request mcp.PaginatedRequest,
method string,
) (*T, error) {
response, err := client.sendRequest(ctx, method, request.Params)
response, err := client.sendRequest(ctx, method, request.Params, nil)
if err != nil {
return nil, err
}
Expand Down
2 changes: 2 additions & 0 deletions client/transport/interface.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ package transport
import (
"context"
"encoding/json"
"net/http"

"github.com/mark3labs/mcp-go/mcp"
)
Expand Down Expand Up @@ -59,6 +60,7 @@ type JSONRPCRequest struct {
ID mcp.RequestId `json:"id"`
Method string `json:"method"`
Params any `json:"params,omitempty"`
Header http.Header `json:"-"`
}

type JSONRPCResponse struct {
Expand Down
26 changes: 16 additions & 10 deletions client/transport/streamable_http.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ func (c *StreamableHTTP) SendRequest(
ctx, cancel := c.contextAwareOfClientClose(ctx)
defer cancel()

resp, err := c.sendHTTP(ctx, http.MethodPost, bytes.NewReader(requestBody), "application/json, text/event-stream")
resp, err := c.sendHTTP(ctx, http.MethodPost, bytes.NewReader(requestBody), "application/json, text/event-stream", request.Header)
if err != nil {
if errors.Is(err, ErrSessionTerminated) && request.Method == string(mcp.MethodInitialize) {
// If the request is initialize, should not return a SessionTerminated error
Expand Down Expand Up @@ -339,13 +339,19 @@ func (c *StreamableHTTP) sendHTTP(
method string,
body io.Reader,
acceptType string,
header http.Header,
) (resp *http.Response, err error) {
// Create HTTP request
req, err := http.NewRequestWithContext(ctx, method, c.serverURL.String(), body)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}

// request headers
if header != nil {
req.Header = header
}

Comment on lines +350 to +354
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Header assignment may not preserve all default headers.

When a custom header is provided, the code replaces the entire req.Header with the provided header. This could potentially lose important default headers that http.NewRequestWithContext sets up (like Host, User-Agent, etc.).

Consider merging headers instead of replacing:

-	// request headers
-	if header != nil {
-		req.Header = header
-	}
-
+	// Merge custom headers if provided
+	if header != nil {
+		for key, values := range header {
+			for _, value := range values {
+				req.Header.Add(key, value)
+			}
+		}
+	}

Alternatively, if the intention is to allow complete header control, consider cloning the header first to avoid modifying the original:

-	// request headers
-	if header != nil {
-		req.Header = header
-	}
-
+	// Use custom headers if provided
+	if header != nil {
+		req.Header = header.Clone()
+	}
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
// request headers
if header != nil {
req.Header = header
}
// Merge custom headers if provided
if header != nil {
for key, values := range header {
for _, value := range values {
req.Header.Add(key, value)
}
}
}
🤖 Prompt for AI Agents 
In client/transport/streamable_http.go around lines 350 to 354, the code
replaces req.Header with the provided header which can discard default headers;
instead merge the provided header into the existing req.Header (iterating keys
and appending values) so you preserve defaults like Host and User-Agent, or if
full control was intended, first clone the provided header and assign the clone
to req.Header to avoid mutating the caller's header; implement one of these two
approaches and ensure you append values rather than overwrite per header key.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@matthisholleville could you address this please?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

// Set headers
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Accept", acceptType)
Expand Down Expand Up @@ -546,7 +552,7 @@ func (c *StreamableHTTP) SendNotification(ctx context.Context, notification mcp.
ctx, cancel := c.contextAwareOfClientClose(ctx)
defer cancel()

resp, err := c.sendHTTP(ctx, http.MethodPost, bytes.NewReader(requestBody), "application/json, text/event-stream")
resp, err := c.sendHTTP(ctx, http.MethodPost, bytes.NewReader(requestBody), "application/json, text/event-stream", nil)
if err != nil {
return fmt.Errorf("failed to send request: %w", err)
}
Expand Down Expand Up @@ -605,7 +611,7 @@ func (c *StreamableHTTP) listenForever(ctx context.Context) {
connectCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
err := c.createGETConnectionToServer(connectCtx)
cancel()

if errors.Is(err, ErrGetMethodNotAllowed) {
// server does not support listening
c.logger.Errorf("server does not support listening")
Expand All @@ -621,7 +627,7 @@ func (c *StreamableHTTP) listenForever(ctx context.Context) {
if err != nil {
c.logger.Errorf("failed to listen to server. retry in 1 second: %v", err)
}

// Use context-aware sleep
select {
case <-time.After(retryInterval):
Expand All @@ -639,7 +645,7 @@ var (
)

func (c *StreamableHTTP) createGETConnectionToServer(ctx context.Context) error {
resp, err := c.sendHTTP(ctx, http.MethodGet, nil, "text/event-stream")
resp, err := c.sendHTTP(ctx, http.MethodGet, nil, "text/event-stream", nil)
if err != nil {
return fmt.Errorf("failed to send request: %w", err)
}
Expand Down Expand Up @@ -704,15 +710,15 @@ func (c *StreamableHTTP) handleIncomingRequest(ctx context.Context, request JSON
// Create a new context with timeout for request handling, respecting parent context
requestCtx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()

response, err := handler(requestCtx, request)
if err != nil {
c.logger.Errorf("error handling request %s: %v", request.Method, err)

// Determine appropriate JSON-RPC error code based on error type
var errorCode int
var errorMessage string

// Check for specific sampling-related errors
if errors.Is(err, context.Canceled) {
errorCode = -32800 // Request cancelled
Expand All @@ -731,7 +737,7 @@ func (c *StreamableHTTP) handleIncomingRequest(ctx context.Context, request JSON
errorMessage = err.Error()
}
}

// Send error response
errorResponse := &JSONRPCResponse{
JSONRPC: "2.0",
Expand Down Expand Up @@ -771,7 +777,7 @@ func (c *StreamableHTTP) sendResponseToServer(ctx context.Context, response *JSO
ctx, cancel := c.contextAwareOfClientClose(ctx)
defer cancel()

resp, err := c.sendHTTP(ctx, http.MethodPost, bytes.NewReader(responseBody), "application/json")
resp, err := c.sendHTTP(ctx, http.MethodPost, bytes.NewReader(responseBody), "application/json", nil)
if err != nil {
c.logger.Errorf("failed to send response to server: %v", err)
return
Expand Down
53 changes: 53 additions & 0 deletions client/transport/streamable_http_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,7 @@ func startMockStreamableHTTPServer() (string, func()) {
"jsonrpc": "2.0",
"id": request["id"],
"result": request,
"headers": r.Header,
}); err != nil {
http.Error(w, "Failed to encode response", http.StatusInternalServerError)
return
Expand Down Expand Up @@ -122,6 +123,24 @@ func startMockStreamableHTTPServer() (string, func()) {
http.Error(w, "Failed to encode response", http.StatusInternalServerError)
return
}
case "debug/echo_header":
// Check session ID
if r.Header.Get("Mcp-Session-Id") != sessionID {
http.Error(w, "Invalid session ID", http.StatusNotFound)
return
}

// Echo back the request headersas the response result
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
if err := json.NewEncoder(w).Encode(map[string]any{
"jsonrpc": "2.0",
"id": request["id"],
"result": r.Header,
}); err != nil {
http.Error(w, "Failed to encode response", http.StatusInternalServerError)
return
}
}
})

Expand Down Expand Up @@ -215,6 +234,40 @@ func TestStreamableHTTP(t *testing.T) {
}
})

t.Run("SendRequestWithHeader", func(t *testing.T) {
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

params := map[string]any{
"string": "hello world",
"array": []any{1, 2, 3},
}

request := JSONRPCRequest{
JSONRPC: "2.0",
ID: mcp.NewRequestId(int64(1)),
Method: "debug/echo_header",
Params: params,
Header: http.Header{"X-Test-Header": {"test-header-value"}},
}

// Send the request
response, err := trans.SendRequest(ctx, request)
if err != nil {
t.Fatalf("SendRequest failed: %v", err)
}

// Parse the result to verify echo
var result map[string]any
if err := json.Unmarshal(response.Result, &result); err != nil {
t.Fatalf("Failed to unmarshal result: %v", err)
}

if hdr, ok := result["X-Test-Header"].([]any); !ok || len(hdr) == 0 || hdr[0] != "test-header-value" {
t.Errorf("Expected X-Test-Header to be ['test-header-value'], got %v", result["X-Test-Header"])
}
})

t.Run("SendRequestWithTimeout", func(t *testing.T) {
// Create a context that's already canceled
ctx, cancel := context.WithCancel(context.Background())
Expand Down