Support custom header names for MCP servers secured with Auth Providers

[HonzaKopecky]

When securing third-party Model Context Protocol (MCP) servers or web APIs via Google Cloud Agent Identity, we often register an API Key connector using gcloud alpha agent-identity connectors create <name> --api-key="<secret>" or newer gcloud alpha agent-identity authProviders create ...(which, funnily enough, isn't supported bygcloud alpha agent-registry bindings create --auth-provider-binding`, so one is forced to use the old (never-will-be-released way).

Under the hood, the GCP IAM Connector Credentials service returns this key under standard API Key headers (e.g. X-API-Key). However, many third-party MCP servers and proprietary APIs which strictly expect API tokens to be formatted in the standard HTTP Authorization header with a Bearer prefix (i.e. Authorization: Bearer ).

Currently, internal _construct_auth_credential method in _iam_connector_credentials_provider.py hardcodes custom API Key connector payloads to fall back only to X-GOOG-API-KEY and the raw connector's header:

      # Handle custom header.                                                                                                                                                                   
      return AuthCredential(                                                                                                                                                                    
          auth_type=AuthCredentialTypes.HTTP,                                                                                                                                                   
          http=HttpAuth(                                                                                                                                                                        
              scheme="",                                                                                                                                                                        
              credentials=HttpCredentials(),                                                                                                                                                    
              additional_headers={                                                                                                                                                              
                  response.header: response.token,                                                                                                                                              
                  "X-GOOG-API-KEY": response.token,                                                                                                                                             
              },                                                                                                                                                                                
          ),                                                                                                                                                                                    
      )

As a result, there is no native way to instruct the ADK to format a secure, GCP-fetched API Key credential into Authorization: Bearer <token> format (or any other custom format), forcing developers to subclass and override GcpAuthProvider to perform runtime credential re-wrapping.

──────

Describe the Solution You'd Like

We would like the ability to specify custom header formatting (such as changing the header name and applying a scheme/prefix) directly when resolving toolsets from the registry.

Specifically, get_mcp_toolset should accept optional parameters for:

1. http_scheme: (e.g. "Bearer", "Basic") to determine the RFC7235 prefix.
2. header_name: (e.g. "Authorization") to specify the target header.

When these are defined, the credential resolver should automatically construct a standard HttpAuth with the requested scheme and token instead of defaulting to X-GOOG-API-KEY as a custom header.

──────

Impact on your work

This feature is highly important for streamlining production-grade deployments. It allows us to integrate our agents with secure, third-party MCP servers hosted on platforms like Cloud Run (which use standard OAuth or Bearer authorization headers) using GCP's platform-native Agent Identity bindings, without maintaining custom Python-side wrapper decorators or provider subclasses.

──────

Willingness to contribute

Yes.

──────

🟡 Recommended Information

Describe Alternatives You've Considered

We have successfully implemented a client-side workaround by registering a custom subclass of GcpAuthProvider with the CredentialManager:

    class UptimeifyGcpAuthProvider(GcpAuthProvider):                                                                                                                                            
        async def get_auth_credential(self, auth_config, context=None):                                                                                                                         
            credential = await super().get_auth_credential(auth_config, context)                                                                                                                
            scheme_name = getattr(auth_config.auth_scheme, "name", "")                                                                                                                          
            if scheme_name and "uptimeify-key-connector" in scheme_name:                                                                                                                        
                if credential and credential.http and credential.http.additional_headers:                                                                                                       
                    headers = credential.http.additional_headers                                                                                                                                
                    token = headers.get("X-API-Key") or headers.get("X-GOOG-API-KEY")                                                                                                           
                    if token:                                                                                                                                                                   
                        return AuthCredential(                                                                                                                                                  
                            auth_type=AuthCredentialTypes.HTTP,                                                                                                                                 
                            http=HttpAuth(                                                                                                                                                      
                                scheme="Bearer",                                                                                                                                                
                                credentials=HttpCredentials(token=token)                                                                                                                        
                            )                                                                                                                                                                   
                        )                                                                                                                                                                       
            return credential                                                                                                                                                                   
                                                                                                                                                                                                
    CredentialManager.register_auth_provider(UptimeifyGcpAuthProvider())

While this works, it adds unnecessary boilerplate to the agent setup which would otherwise be super straightforward.

──────

Proposed API / Implementation

We propose exposing this configuration during get_mcp_toolset call:

    uptimeify_mcp_toolset = registry_us.get_mcp_toolset(
        "projects/my-project/locations/us-central1/mcpServers/agentregistry-uuid",
        http_scheme="Bearer",       # New parameter
        header_name="Authorization" # New parameter
    )

Additional Context

I would agree the best solution would be for the IAM Connectors or Auth Providers API to support the header_name but I am afraid we have little control over that.

[sanketpatil06]

Hi @HonzaKopecky, thanks for raising this! The request is currently under review, and we will let you know if anything further is needed. Thank you for your patience.