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.

What gets captured

Agent Handler keeps any header that starts with X-, plus Mcp-Session-Id. Every other header is dropped before the call is logged, so only your X- metadata and the session ID appear in the logs.

Agent Handler doesn’t enforce a cap on the number of custom headers or their length. Keep names and values short and ASCII so they stay readable in the logs and in whatever you forward them to. Very large header sets can still be rejected by the HTTP layer before they reach Agent Handler.

Next

Filter by your custom headers in the Tool Call Logs.