retoor
251c3dc2ba
- 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)
58 lines
4.1 KiB
Markdown
58 lines
4.1 KiB
Markdown
# 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. |
|