BuildConnecting agents

Custom headers for MCP

Tag tool calls with metadata for filtering, tracing, and grouping in the logs.

Any header you send with the MCP request that starts with X- is captured as metadata on the tool call. The headers show up in the Tool Call Logs as a filterable column, so you can group calls by whatever dimension matters to you - chat session, workflow run, environment, customer ID.

Why bother

Three patterns most teams find useful.

Per-session filtering. Set X-Chat-Id: <session_id> from your agent runtime. Now you can filter the logs to one user’s conversation and see exactly what tools fired across the whole turn.

Tracing into your APM. If your existing tracing system uses a request ID, send it as X-Request-Id. Cross-reference between Agent Handler logs and your APM by ID instead of by timestamp.

Environment isolation. X-Environment: production vs X-Environment: staging - useful when one Agent Handler org serves both, and you want to filter logs by where the call came from.

Adding headers

Send them on the MCP request - exactly the same way you send Authorization. The Python MCP SDK example:

1import asyncio
2from mcp.client.streamable_http import streamablehttp_client
3from mcp import ClientSession
4
5async def run(chat_id: str, user_id: str):
6    headers = {
7        "Authorization": "Bearer <YOUR_API_KEY>",
8        "X-Chat-Id": chat_id,
9        "X-User-Id": user_id,
10        "X-Environment": "production",
11    }
12    url = "https://ah-api.merge.dev/api/v1/tool-packs/<TPID>/registered-users/<RUID>/mcp"
13
14    async with streamablehttp_client(url, headers=headers) as (read, write, _):
15        async with ClientSession(read, write) as session:
16            await session.initialize()
17            # Headers apply to every tool call made through this session.
18            ...

Headers attach to every tool call sent within the session. To change them per call, open a new session.

The same works in TypeScript or any HTTP client - just include the headers on the underlying request.

Filtering in the dashboard

Open Logs → Tool calls. The filter bar has a Custom headers option that lets you filter by header name and value.

Multiple header filters compose - “all calls with X-Chat-Id = abc123 AND X-Environment = production.”

Reserved headers

A few headers are special and won’t show up as filterable custom metadata:

  • Authorization - your Access Key.
  • Content-Type, Accept - standard HTTP.
  • Mcp-Session-Id - used by MCP for session correlation; logged separately.

Anything else with an X- prefix is yours.

Limits

Max headers per request16
Max header name length64 chars
Max header value length256 chars
Allowed charactersASCII printable. Don’t put binary or multi-byte content in header values.

If you exceed the limits, the request still goes through - Agent Handler just truncates or drops the offending headers and logs a warning in the API Request Log.

Next

Filter by your custom headers in the Tool Call Logs.