Python: [Bug]: Support custom HTTP headers in declarative YAML MCP tool definitions

[AnaNeri]

Description

When defining an MCP tool inside a declarative YAML agent (kind: Prompt) or workflow (kind: workflow), there is no way to specify custom HTTP headers.
The tools schema does not not allows headers property.
In declarative workflows and prompts headers change with when using ApiKeyConnection.

This is a blocker for any MCP server that requires custom headers for authentication or routing.

It should be possible to declare custom HTTP headers directly in the YAML MCP tool definition, ideally with support for environment variable expressions (consistent with how url already supports =Env.MCP_URL):

tools:
  - kind: mcp
    name: product-mcp
    description: Product MCP server
    url: =Env.MCP_URL
    headers:                          # ← missing feature
      X-ERP-Host: =Env.X_ERP_HOST
      X-ERP-Instance: =Env.X_ERP_INSTANCE
      X-ERP-CompanyKey: =Env.X_ERP_COMPANY_KEY
      X-ERP-WebApiVersion: =Env.X_ERP_API_VERSION
      X-ERP-AccessToken: =Env.X_ERP_ACCESS_TOKEN

This would be more inline with the hardcoded implementation of MCP clients and would avoid verbose workarounds like the one in Code sample.

Code Sample

import asyncio
import os
from agent_framework.declarative import AgentFactory
from agent_framework.openai import OpenAIResponsesClient

from dotenv import load_dotenv
load_dotenv()

YAML_AGENT = """
kind: Prompt
name: ValidationAgent
description: Agent responsible for validating customer information using MCP tool.
instructions: |
    You are a helpful assistant responsible for validating customer information using the Product MCP tool. When you
model:
    id: gpt-4.1
    provider: AzureOpenAI.Responses
"""

async def run_agent():
    headers = {
        "X-ERP-Host": os.getenv("X-ERP-Host", ""),
        "X-ERP-Instance": os.getenv("X-ERP-Instance", ""),
        "X-ERP-CompanyKey": os.getenv("X-ERP-CompanyKey", ""),
        "X-ERP-WebApiVersion": os.getenv("X-ERP-WebApiVersion", ""),
        "X-ERP-AccessToken": os.getenv("X-ERP-AccessToken", "")
    }

    mcp_tool = OpenAIResponsesClient.get_mcp_tool(
        name="product-mcp",
        description="Product MCP server",
        url=os.getenv("MCP_URL"),
        headers=headers,
        approval_mode="never_require",
    )

    async with AgentFactory(safe_mode=False).create_agent_from_yaml(YAML_AGENT) as agent:
        query = "Check the state of client with email teste@teste.com"
        print(f"\nUser: {query}")
        response = await agent.run(query, tools=[mcp_tool])
        print(f"\nAgent: {response.text}")

Error Messages / Stack Traces

Package Versions

agent-framework-1.0.0rc2; agent-framework-declarative-1.0.0b260304

Python Version

Python 3.13

Additional Context

The workaround works but forces imperative tool construction, breaking the declarative/YAML-first development model and complicating production deployments that rely on workflow config files without code changes.

[mykolademyanov]

Good callout. url already supports =Env.* so the missing headers support is a clear inconsistency.

This is a broader pattern where declarative layers break down when the runtime and config aren't in sync — more on that here: https://agentpatterns.tech/en/architecture/agent-runtime

Is ApiKeyConnection meant to cover this eventually, or is headers support a separate track?

[agmpt]

We would prefer explicit support for headers in the YAML definition.

In our case the MCP tool needs to send several headers that are required for the MCP server to authenticate and resolve the correct tenant when calling a multi-tenant API.

These headers are not just a single API key and do not fit well into the ApiKeyConnection abstraction. They represent request context required by the MCP server in order to authenticate and route the request.

Because of that, having explicit headers support in the declarative MCP tool configuration would allow us to keep the entire tool definition in YAML instead of falling back to imperative construction in Python.

[eavanvalkenburg]

So this is not something we can do, we implement the AgentSchema: https://microsoft.github.io/AgentSchema/reference/mcptool/ so I created a issue there, linked to this one, once that is added to the schema, we can also add it here.