fix: MCP authorization parameter implementation

[omaryashraf5]

What does this PR do?

Adding a user-facing authorization parameter to MCP tool definitions that allows users to explicitly configure credentials per MCP server, addressing GitHub Issue #4034 in a secure manner.

Test Plan

tests/integration/responses/test_mcp_authentication.py

[bbrowning]

Can you point me to where in the Responses API spec it has this authentication attribute? I only see authorization listed for MCP tools.

[omaryashraf5]

@bbrowning Thanks for your comment! Yes, I changed it to 'authorization' However, this static approach would only be helpful for MCP credentials that are hardcoded in tool definitions (long lived tokens). But its not ideal for cases where we need to have different mcp credentials per user. Automatically forwarding the user's OAuth token to MCP server is not an option, so an alternative approach would be for the user to explicitly pass their own OAuth token through the client? (dynamic per-request)

[bbrowning]

@bbrowning Thanks for your comment! Yes, I changed it to 'authorization' However, this static approach would only be helpful for MCP credentials that are hardcoded in tool definitions (long lived tokens). But its not ideal for cases where we need to have different mcp credentials per user.

I'm not sure I follow what you're saying. Every inference request passes in the tools available for that request. So, with every inference request, the client can pass in an updated token for any MCP servers that request references. And that means every user also passes in their own credentials. Or, am I misunderstanding how you intend this to work?

[omaryashraf5]

@bbrowning Thanks for your comment! Yes, I changed it to 'authorization' However, this static approach would only be helpful for MCP credentials that are hardcoded in tool definitions (long lived tokens). But its not ideal for cases where we need to have different mcp credentials per user.

I'm not sure I follow what you're saying. Every inference request passes in the tools available for that request. So, with every inference request, the client can pass in an updated token for any MCP servers that request references. And that means every user also passes in their own credentials. Or, am I misunderstanding how you intend this to work?

This PR supports the case where authorization tokens change between response creation requests.

For example:

response1 = client.responses.create(
model="llama3",
input="What is X?",
tools=[{"type": "mcp", "authorization": {"token": "user_a_token"}}]
)

response2 = client.responses.create(
model="llama3",
input="What is Y?",
tools=[{"type": "mcp", "authorization": {"token": "user_b_token"}}] # Different token
)

within a single response, multiple inference iterations happen --> authorization tokens can not be updated between these inference iterations.

Internally, this might do:

• Inference iteration 1 → calls MCP with "initial_token"
• Inference iteration 2 → calls MCP with "initial_token" (same token)
• Inference iteration 3 → calls MCP with "initial_token" (same token)
  Question: Can the token be refreshed between iterations 1→2→3?
  No

[omaryashraf5]

this approach is static within each individual response but dynamic across responses.

[mattf]

remove all the reformatting and make it clear what is being changed.

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged. @omaryashraf5 please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[omaryashraf5]

OK @omaryashraf5 given the number of iterations on this PR, let's get this in today even if this requires us to do a few trade-offs. Otherwise we will forever be in limbo. Iterative movement is far better than stuck trying to get to some kind of perfect ideal (which doesn't even last anyway) in a single PR.

• do add the new authorization parameter to the /tool-runtime APIs, but don't use it in the tests yet
• keep the tests working with the older Authorization provider data header and so keep honoring that header so that the tests pass
• in the follow-up PR, we will land the Stainless changes (they will land automatically) to the SDK -- so you can clean-up and use the new authorization parameter and completely remove support for the header.

Let's get this PR green and I will get this merged.

cc @mattf FYI

Thanks, @ashwinb ! Will do!

[ashwinb]

Btw see this comment from the Stainless bot now #4052 (comment) and see the associated python SDK diff https://github.com/stainless-sdks/llama-stack-client-python/compare/preview/base/add-mcp-authentication-param..preview/add-mcp-authentication-param -- looks all good.

[omaryashraf5]

https://github.com/stainless-sdks/llama-stack-client-python/compare/preview/base/add-mcp-authentication-param..preview/add-mcp-authentication-param

Thanks, @ashwinb for some reason I am not authorized to access that page/repo

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged. @omaryashraf5 please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[omaryashraf5]

MCP Authentication Parameter Migration - Phase 1 & 2

Phase 1: Add Authorization Parameter with Backward Compatibility (Implemented)

What Was Done:

1. API Changes - Added authorization: str | None = None parameter to:

   • responses api
   • /tool-runtime/list-tools endpoint (Tool Runtime API)
   • /tool-runtime/invoke endpoint (Tool Runtime API)
   • Both documented as "OAuth access token for authenticating with the MCP server"

2. Implementation Changes:

   • Updated list_runtime_tools() and invoke_tool() in model_context_protocol.py to accept the new parameter
   • Implemented dual authorization support: accepts both old header-based AND new parameter-based auth for now but that will change after merging this PR and the stainless release such that the authorization token will only be accepted directly from the authroization field (outside the header).
   • Created get_headers_from_request() to extract authorization from X-LlamaStack-Provider-Data header
   • This accepts the OLD client approach: passing auth via provider data headers
   • New authorization parameter takes precedence: final_authorization = authorization or provider_auth
   • Enables gradual migration: both old and new approaches work simultaneously but that will change after merging this PR. The old approach will be eliminated in favor of the new approach in the cleanup PR (Phase 2).

3. Security Layer:

   • Added prepare_mcp_headers() utility in mcp.py that validates and prepares headers
   • Strict validation: Rejects if Authorization is found in the headers dict (security risk)
   • Enforces separation: users must use the dedicated authorization parameter instead
   • Automatically adds "Bearer " prefix when constructing final HTTP headers to MCP server

4. Test Updates:

   • Updated api_recorder.py to pass authorization parameter through patched tool methods
   • Integration tests continue using old header-based approach via X-LlamaStack-Provider-Data header
   • Added comments clarifying Phase 1 backward compatibility behavior

Why Backward Compatibility Was Necessary:

• Timing Issue: New client SDK with authorization parameter doesn't exist yet
  • Waiting for Stainless to auto-generate
  • Current SDK only supports old header-based authentication
• Test Dependencies: Cannot update tests until new SDK is available
  • Tests currently use extra_headers with provider data: {"mcp_headers": {uri: {"Authorization": "Bearer token"}}}
  • New SDK will support clean parameter: authorization="token"

Current Behavior (Phase 1):

# Old approach (still works - backward compatible)
provider_data = {"mcp_headers": {uri: {"Authorization": f"Bearer {token}"}}}
auth_headers = {"X-LlamaStack-Provider-Data": json.dumps(provider_data)}
client.tool_runtime.list_tools(tool_group_id=id, extra_headers=auth_headers)

# New approach (already works!)
client.tool_runtime.list_tools(tool_group_id=id, authorization=token)

# If both provided, new parameter wins
client.tool_runtime.list_tools(
    tool_group_id=id, 
    authorization=token,        # ← This takes precedence
    extra_headers=auth_headers  # ← Ignored if above is provided
)

Phase 2 (Follow-up PR): Remove Backward Compatibility (after Stainless release) and extract authorization from the dedicated authorization field.

[mergify]

This pull request has merge conflicts that must be resolved before it can be merged. @omaryashraf5 please rebase it. https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[ashwinb]

I don't see why this is needed? There was a failure on trunk due to toolgroups register missing, but that was resolved. And the reason was a bad llama-stack-client-python update earlier in the day. You should not need this mark, please remove it.