Files

T

retoor 251c3dc2ba research: mcp-client-support subject (106 sources, 3 conclusions)

- wire spec: lifecycle, stdio + Streamable HTTP transports, tools,
  utilities, legacy SSE, versioning, changelog (14 Tier 1)
- client ecosystem: Claude Code/VS Code/Cursor/Codex configs,
  mcp-remote, Smithery, registries, Glama (12 Tier 1)
- security/ops: authorization draft, trust model, poisoning,
  rug pulls, production hardening (12 Tier 1) + 68 Tier 2 cards
- conclusions: minimal stdlib client on 2025-11-25, normalizer +
  resolver agent for pasted configs/GitHub URLs, untrusted-until-
  consent trust model; nothing built yet
- audit PASS (14 subjects, 797 sources, 32 conclusions)

2026-10-18 19:23:02 +02:00

4.1 KiB

Raw Blame History

Connect Claude Code to tools via MCP (official Claude Code docs)

Metadata

Field	Value
Institute	Molodetz Institute - Research and Retrieval Division
Subject	mcp-client-support
Document type	Source Dossier
Tier	1
Source title	Connect Claude Code to tools via MCP
Source URL	https://code.claude.com/docs/en/mcp
Source publisher / author	Anthropic
Source type	vendor docs
Source date (published)	Unknown, not stated (living doc; cites CLI versions v2.1.246 to v2.1.268, so current to about 2026)
Date researched	2026-10-18
Researched by	tai (agent), model: Claude Sonnet 5, on behalf of retoor
Research method	gather-subagent direct page fetch, parent synthesis from evidence pack
Confidence	High
Status	Active

Summary

Official Anthropic documentation for configuring MCP servers in Claude Code. It defines the project .mcp.json shape (mcpServers object with remote {"type": "http", "url": ...} entries), the ${VAR} / ${VAR:-default} expansion syntax and its five valid locations, a credential guardrail that blanks sensitive variable names in remote URLs and headers, and the three-scope model (local, project, user) plus an overriding org managedMcpServers layer.

Key findings

Project .mcp.json uses a top-level mcpServers object; a remote entry is {"type": "http", "url": "https://example.com/mcp"} ("The resulting .mcp.json file follows a standardized format").
type accepts streamable-http as an alias for http: "configurations copied from server documentation work without modification."
"A JSON entry that has a url but no type is a configuration error, because Claude Code reads an entry with no type as a stdio server."
Env expansion syntax is exactly ${VAR} ("expands to the value of environment variable VAR") and ${VAR:-default} ("expands to VAR if set, otherwise uses default"), valid in five locations: command, args, env, url, headers.
Unset var without default: "the config still loads... and uses the unexpanded ${VAR} text as-is", plus a missing-variable warning naming the variable.
Credential guardrail: in remote url/headers, names like ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY, NPM_TOKEN "read as empty... A covered name reads as empty whether or not you have set the variable, and a :-default fallback on it is ignored."
Three scopes: local (default, ~/.claude.json under project path), project (.mcp.json, committed, requires interactive approval; claude mcp reset-project-choices), user (~/.claude.json, all projects); plus org managedMcpServers which "ranks above all of these."
Enable/disable: disabledMcpServers (opt-out) / enabledMcpServers (opt-in for default-off built-ins) are "unrelated to enabledMcpjsonServers and disabledMcpjsonServers, which control approval of servers defined in a project's .mcp.json".

Pros / strengths

Authoritative: the vendor's own statement of the config contract, so pasted-config shapes derived from it are first-party.
Unusually explicit about failure modes: the missing-type error rule, the unexpanded-text fallback, and the credential-guardrail list are stated as exact behaviors, not hints.
The scope and approval model (local/project/user/org, approval-gated project entries) is documented end to end rather than left to experiment.

Cons / limitations / caveats

Living doc with no publish date; currency is inferred from in-text CLI version references, not a version stamp.
Documents one client's conventions only; nothing here constrains how other clients expand variables or scope servers.
Original URL https://docs.anthropic.com/en/docs/claude-code/mcp redirected to https://code.claude.com/docs/en/mcp at fetch time, so old bookmarks and citations rot.

Relevance to tai

Defines the canonical pasted-config shape to normalize: mcpServers wrapper plus type repair plus ${VAR} expansion plus the scope/approval model. This is the reference input dialect for tai's resolver.

Changelog

Date	Change
2026-10-18	Initial dossier created.

4.1 KiB Raw Blame History