Tool dropped for an invalid x-mcp-header

If your server or client is the MCP TypeScript SDK 2.x

1. 1 Read the warning from whichever side logged it, because both sides have one and they are worded differently. The client logs [mcp-sdk] excluding tool '<name>' from tools/list: invalid x-mcp-header declaration — <reason> when it drops the tool. McpServer.registerTool warns at registration time instead: [mcp-sdk] tool '<name>' carries an invalid x-mcp-header declaration and will be excluded by conforming Streamable HTTP clients: <reason>. That server-side warning fires whether or not any client has connected, so it is the faster place to look.
2. 2 Take the reason literally — the SDK names the failing property path and the constraint. Its messages cover the five cases separately: not statically reachable via a chain of 'properties' keys, not a non-empty string, not a valid RFC 9110 token, not on a primitive-typed property, and not case-insensitively unique.
3. 3 Expect the exclusion on the client to be skipped over stdio. The client applies it only on a modern-era connection that is not stdio, so the same malformed tool stays visible to a stdio client and vanishes over Streamable HTTP. The server-side registration warning does not make that distinction and is the one to trust.
4. 4 Clear the client's cached listing after you fix the schema. The exclusion is applied to the cached aggregated tools/list result as well as to each returned page, so a still-fresh cache entry keeps the tool missing; cacheMode: 'refresh' on the call forces a fetch.
5. 5 Do not reach for x-mcp-header in a browser-resident client. The SDK skips mirroring there, because dynamically named headers cannot be statically allowlisted for credentialed CORS, and a conforming server then rejects the tools/call for the missing header. The SDK documents this as a known limitation rather than a bug.

// Rejected: the annotation is under `items`, so it is not statically
// reachable through a chain of `properties` keys.
inputSchema: {
  type: 'object',
  properties: {
    regions: {
      type: 'array',
      items: { type: 'string', 'x-mcp-header': 'Region' }
    }
  }
}

// Accepted: a primitive property reached through `properties` only.
inputSchema: {
  type: 'object',
  properties: {
    region: { type: 'string', 'x-mcp-header': 'Region' },
    query: { type: 'string' }
  },
  required: ['region', 'query']
}

If the client dropping the tool is the MCP Python SDK 2.x

1. 1 Search your logs for dropping tool rather than for the tool name. The client session logs dropping tool '<name>': invalid x-mcp-header (<reason>) at warning level as it filters the listing, and it also evicts any argument-to-header map it had cached for that tool from an earlier, valid listing.
2. 2 Expect the Python client to drop the tool on stdio as well. It gates the filter on the negotiated protocol version alone, with no transport carve-out, so a tool that a TypeScript client still shows over stdio disappears here. That difference is a real one between the two SDKs, not a misconfiguration in your server.
3. 3 Read the reason string for the property path. The validator reports the five cases distinctly: it says the annotation was "found at a schema position not reachable via a pure properties chain" for the unreachable case, and is only permitted on integer/string/boolean properties for a wrong type.
4. 4 Check the annotation survived schema generation when you declare it through Pydantic. It travels as json_schema_extra={"x-mcp-header": "Region"} on the field, and a wrapper that rebuilds the schema — an optional field widened to type: ["string", "null"], for instance — can move it somewhere the validator will not accept.

from pydantic import Field
from typing import Annotated

@mcp.tool()
def execute_sql(
    region: Annotated[
        str,
        Field(json_schema_extra={"x-mcp-header": "Region"}),
    ],
    query: str,
) -> str:
    ...

If the tool belongs to someone else's server and you only consume it

1. 1 Confirm the annotation is the cause before you file anything. A tool present in the raw tools/list and absent from your client is the signature of this exclusion; a tool absent from both is a different problem entirely.
2. 2 Send the maintainer the property path and the reason string. The SDK warnings name both, which is most of a bug report, and a server author who only ever tested over stdio may never have seen the warning — the TypeScript client skips the exclusion on stdio, so the tool works there.
3. 3 Reach the tool over stdio in the meantime, if the server offers that transport and your client is the TypeScript SDK. The exclusion is scoped to non-stdio modern connections there. The Python client applies it on every transport, so this is not a general workaround.
4. 4 Pin the connection to an earlier protocol revision as the other stopgap. The rule arrived in 2026-07-28, so a client that negotiates 2025-11-25 against a server that still serves it returns the tool unfiltered. Treat that as buying days, not as a resting place.
5. 5 Do not expect a capability allowlist to bring it back. mcp-capability-filter-inbound and its equivalents decide which capabilities a route exposes; nothing in front of the client can restore a tool the client removed after reading a successful response.

Something else

Whatever the SDK, the shape is the same: the schema is the fault and the client is the enforcement point, so nothing you change at the transport or the authorization layer will bring the tool back. Read the raw tools/list response to confirm the server still publishes the tool, then find every x-mcp-header in that tool's inputSchema and check each one against the five constraints — non-empty, RFC 9110 token, case-insensitively unique, on a string, integer or boolean property, and reachable through properties keys only. Fix the schema where you can, and expect a cached listing to keep the tool hidden until it is refreshed. Where the server is not yours, send the maintainer the property path from that jq output and treat stdio or an earlier negotiated revision as the stopgap. One thing to rule out before you start: a valid annotation still adds a header to every matching tools/call, so a signing or header-allowlisting layer that did not expect Mcp-Param-* fails separately and later.