MCP Toolbox HTTP Source - Header Parameter don't allow headers with hyphen.

[riaz]

Prerequisites

• I've searched the current open issues
• I've updated to the latest version of Toolbox
• I've updated to the latest version of the SDK

Toolbox version

0.28.0+Homebrew.darwin.arm64

Environment

1. OS type and version: (output of uname -a) - Darwin riazs-MacBook-Pro-2.local 25.2.0 Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:41 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6031 arm64
2. How are you running Toolbox:

• As a downloaded binary (e.g. from curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox) - brew install mcp-toolbox
• As a container (e.g. from us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION)
• Compiled from source (include the command used to build)

3. Python version (output of python --version) - 3.12.11
4. pip version (output of pip --version) - 25.3

Client

1. Client: .
2. Version: (pip show <package-name>)? e.g.

• toolbox-langchain version 0.6.0

3. Example: If possible, please include your code of configuration:

async with ToolboxClient("http://127.0.0.1:5000", protocol=Protocol.MCP) as toolbox:
    toolbox_tools = toolbox.load_toolset()

  agent = create_agent(
        model,
        tools=toolbox_tools,
        system_prompt=(
            "You are a Question Answering Agent that replies user queries from a known knowledge base"
        ),
        middleware=[SkillMiddleware()],
        checkpointer=InMemorySaver(),
    )

anon-src:
    kind: http
   baseUrl: <vectordb_src_url>
   
retrieve:
    kind: http
    source: anon-src
    method: POST
    path: /get_data
    headers:
      Content-Type: application/json
  
    description: Retrieve relevant content chunks from the vector database based on a query
    requestBody: |
      {
        "message": {
          "role": "user",
          "content": {
            "text": {{json .text}}
          }
        }
      }
    bodyParams:
      - name: text
        description: The query text to retrieve relevant chunks against
        type: string
    headerParams:
       - name: X-Token
         description: Application Token
         type: string
       - name: X-Application-ID
         description: Application ID
        type: string

Expected Behavior

The HeaderParams work as expected in the MCP Inspector , but when loading the ToolBox using the langchain client, I expect to see similar behavior where the LLM can successfully pass the required header params, but i get a error instead - since the headers with - hyphen fail validation.

Current Behavior

118 elif self.has_default:
119 default_value = self.default
--> 121 return Parameter(
122 self.name,
123 Parameter.POSITIONAL_OR_KEYWORD,
124 annotation=self.__get_type(),
125 default=default_value,
126 )

File ~/.pyenv/versions/3.12.11/lib/python3.12/inspect.py:2782, in Parameter.init(self, name, kind, default, annotation)
2780 is_keyword = iskeyword(name) and self._kind is not _POSITIONAL_ONLY
2781 if is_keyword or not name.isidentifier():
-> 2782 raise ValueError('{!r} is not a valid parameter name'.format(name))
2784 self._name = name

ValueError: 'X-Application-ID' is not a valid parameter name

Steps to reproduce?

1. Create the tools.yaml file that requeires a headerParam which has hyphen in them
2. Load the tools.yml using toolbox --tools-file tools.yaml
3. load the tools server using -
   4.async with ToolboxClient("http://127.0.0.1:5000", protocol=Protocol.MCP) as toolbox:
   toolbox_tools = toolbox.load_toolset()
4. The Step 4, leads to the error above.
   ...

Additional Details

No response

[anubhav756]

Thank you @riaz for reporting this issue and for providing a clear reproduction case!

Since the Python SDK dynamically creates LangChain tools based on the MCP schema, parameter names with characters like hyphens will cause validation errors because they are not valid Python identifiers.

We would love to get this fixed. Would you be open to proposing a design for how we should handle this parameter name mapping (e.g., sanitizing non-alphanumeric characters to underscores and mapping them back to the original schema names before execution)? Or would you be open to update this condition in the documentation?

If you are interested, we would also be very happy to review a PR for this! Let us know if you have any questions or need pointers on where to start in the codebase.

[anubhav756]

Reopening this issue for #592

Thanks @saurabhkoshatwar for the PR!