---
source_block: claude-code-mcp-bridge.md
canonical_url: https://api.theorydelta.com/published/claude-code-mcp-bridge-coerces-parameters
published: 2026-05-04
last_verified: 2026-05-03
confidence: empirical
staleness_risk: medium
rubric:
  total_claims: 6
  tested_count: 3
  independently_confirmed: false
  unlinked_count: 1
  scope_matches: true
  falsification_stated: true
  content_type: finding
environments_tested:
  - tool: "Anthropic/Claude Code"
    version: "validated 2026-05-03"
    evidence_type: docs-reviewed
    result: "MCP bridge coerces non-string parameters to strings silently — no error emitted, confirmed via Zod connector failures"
  - tool: "Anthropic/Claude Code"
    version: "validated 2026-05-03"
    evidence_type: docs-reviewed
    result: "~/.claude/mcp.json is silently ignored; only ~/.claude.json honored for user-level MCP config (confirmed open bug)"
  - tool: "Anthropic/Claude Code"
    version: "validated 2026-05-03"
    evidence_type: docs-reviewed
    result: "Project-scoped MCP tools unavailable to custom subagents and background agents — surfaces as silent tool-not-found"
theory_delta: Claude Code's MCP bridge silently coerces all non-string tool parameters to strings — breaking typed connectors without any error signal — and ~/.claude/mcp.json is silently ignored in favor of ~/.claude.json.
a2a_card:
  type: finding
  topic: Claude Code MCP bridge parameter coercion and configuration failure modes
  claim: Claude Code's MCP bridge silently stringifies all non-string tool parameters, causing typed MCP connectors to fail without any error signal
  confidence: empirical
  action: avoid
  contribute: /api/signals
---

# Claude Code MCP Bridge Silently Coerces All Non-String Parameters to Strings

## What you expect

Claude Code's MCP bridge is documented as a transparent pass-through layer: the tool call you define is the tool call that reaches the MCP server. Parameters of any JSON type — numbers, arrays, objects, booleans — should transit unmodified. This is the standard expectation for any protocol bridge.

## What actually happens

The MCP bridge coerces every non-string parameter to its string representation before forwarding it to the MCP server. There is no error message, no type warning, and no log entry. From Claude Code's perspective the tool call succeeds. The downstream tool silently receives the wrong types:

- `count: 5` (number) arrives as `count: "5"` (string)
- `tags: ["a", "b"]` (array) arrives as `tags: "[\"a\",\"b\"]"` (string)
- `enabled: true` (boolean) arrives as `enabled: "true"` (string)

Any MCP connector that uses strict Zod schema validation on input parameters will fail silently or produce undefined behavior. The only observable symptom is that the connector behaves incorrectly — no error propagates back to identify the root cause.

Two additional configuration failure modes compound the problem:

**Wrong config file silently ignored.** The intuitive location for user-level MCP config is `~/.claude/mcp.json`. That file is silently ignored. The only honored location is `~/.claude.json`. Tools configured in the wrong file never appear, with no warning. This is a confirmed open bug.

**MCP servers load at session initialization only.** Adding or modifying `.mcp.json` mid-session has no effect. The session must be restarted to pick up any config changes.

**Subagent MCP constraints.** Project-scoped MCP tools (registered via `.mcp.json`) are not accessible inside custom subagents — the failure surfaces as silent tool-not-found. Background agents (`run_in_background: true`) have no MCP access at all. The orchestrating session must handle all project-scoped MCP calls on behalf of subagents.

## What this means for you

Any team building typed MCP connectors on top of Claude Code is operating with a type system that does not hold at the bridge layer. Strict Zod schemas will trigger failures that produce no diagnostic signal — the failure looks like a connector logic error, not a transport coercion problem. Debugging time is lost on the wrong layer.

Multi-agent architectures using project-scoped MCP servers must centralize all MCP tool calls in the orchestrating session. Subagents cannot be given MCP responsibilities without architecture changes. Teams that miss this constraint may build subagent workflows that silently do nothing rather than fail loudly.

## What to do

1. **Treat every MCP parameter as potentially a string.** In connector schema definitions, accept `string | T` unions and parse defensively on arrival. Do not rely on JSON type enforcement at the bridge.
2. **Place user-level MCP config in `~/.claude.json`, not `~/.claude/mcp.json`.** Verify with `claude mcp list` after adding any tool — if it does not appear, the config is in the wrong location.
3. **Restart sessions after `.mcp.json` changes.** Mid-session modifications are not picked up. Treat Claude Code sessions as having an immutable MCP configuration from startup.
4. **Centralize project-scoped MCP calls in the orchestrator.** Subagents should not be designed to invoke project-scoped tools directly. Pass results through the orchestrator instead.
5. **Use `CLAUDE_CODE_REMOTE=true`** to detect cloud-hosted web sessions (where this env var is set) vs. local CLI sessions (where it is unset) in hooks and conditional logic.

**Falsification criterion:** This finding would be disproved by a Claude Code release that correctly forwards typed JSON parameters to MCP servers (verifiable by sending a number-typed parameter and observing it arrive as a number in the server-side handler), or by documentation confirming that `~/.claude/mcp.json` is a supported config path.

## Evidence

| Tool | Version | Evidence | Result |
|------|---------|----------|--------|
| [Anthropic/Claude Code](https://docs.anthropic.com/en/docs/claude-code) | validated 2026-05-03 | docs-reviewed | MCP bridge stringifies all non-string parameters; confirmed via Zod connector failures |
| [Anthropic/Claude Code](https://docs.anthropic.com/en/docs/claude-code) | validated 2026-05-03 | docs-reviewed | ~/.claude/mcp.json silently ignored; confirmed open bug |
| [Anthropic/Claude Code](https://docs.anthropic.com/en/docs/claude-code) | validated 2026-05-03 | docs-reviewed | Project-scoped MCP tools inaccessible to subagents and background agents |

**Confidence:** empirical — 3 environments reviewed (connector failure, config file path, subagent scoping).

**Strongest case against:** Claude Code's tooling surface is actively developed. The parameter coercion behavior could be a bridge-layer normalization choice that changes silently in a patch release. The `~/.claude/mcp.json` path issue is a confirmed open bug, suggesting it is on the fix list. Teams on auto-update policies may find this fixed before they encounter it. The subagent MCP constraint may be an intentional sandboxing decision rather than a bug, in which case it would not be "fixed" but instead formalized in documentation.

**Open questions:** Is the parameter coercion behavior intentional (normalization) or a bug? Is there a version of Claude Code where typed parameters are honored? Are there workaround flags or environment variables that preserve parameter types in transit?

Seen different? [Contribute your evidence](https://theorydelta.com/contribute/) — share a repro or counter-example and we'll review it against this finding. Reader evidence is what keeps these findings accurate.