Verified against Claude Code · 2026-07-20
Scope Claude Code's .mcp.json to the project instead of trusting global defaults
A configuration prompt for a project-level .mcp.json that names exactly which MCP servers this repository needs, keeps secrets out of a file that is often committed, and treats adding a new server as a reviewable trust decision rather than a default the whole team inherits silently.
The prompt
Ready to copy — highlighted parts are example details you can swap.
Produce a project-scoped .mcp.json for D:\CLAUDE\tools.scult.in, plus the accompanying guidance a teammate opening this repo for the first time would need before approving it — a new MCP server is new code with tool-calling access running inside every session in this repo, not a passive config value. MCP SERVERS THIS PROJECT ACTUALLY NEEDS A Postgres MCP server for querying the staging database read-only during debugging, and a Figma MCP server for pulling design-token values referenced in the component library. HOW SECRETS FOR THESE SERVERS ARE HANDLED TODAY The Postgres connection string lives in a local .env file, never committed; each developer has their own read-only staging credential. WHETHER EACH SERVER BELONGS AT PROJECT SCOPE OR USER SCOPE Postgres and Figma both belong at project scope — everyone on this repo debugs against the same staging database and the same design file. WHAT ALREADY EXISTS No .mcp.json exists yet in this repository. PRODUCE 1. The .mcp.json file itself, listing only the servers named above, each with its command, args, and any required env vars referenced by name using the dollar-brace environment-variable substitution syntax MCP configs expect — never a literal token, key, or connection string written directly into the file, since .mcp.json is typically committed to version control and a literal secret in it is a secret leaked to everyone with repository read access, including in the git history after the line is later removed. 2. A short note per server on what tools it exposes and why this specific repository needs it — a server justified by 'might be useful' rather than a concrete task this repo actually does is a larger trust surface than the project needs and should be left out. 3. A .env.example entry for every referenced variable, so a new contributor knows exactly what to set locally without guessing, and confirmation that the real .env is already gitignored. 4. For each server, one line on The Postgres server is a widely used, actively maintained community server; the Figma server is newer and worth a closer look at what it can write, not just read. — is this a first-party or well-known server, or something newer and less audited — since Claude Code will prompt for approval the first time a project's MCP servers are loaded, and that prompt is only useful if a teammate reading it actually knows what they are approving rather than clicking through out of habit. CONSTRAINTS - If No .mcp.json exists yet in this repository. already lists a server not named in the current needs list, flag it explicitly rather than silently dropping or silently keeping it — an unused server still listed is either dead configuration or a sign the needs list above is incomplete. - Do not add a server at project scope if Postgres and Figma both belong at project scope — everyone on this repo debugs against the same staging database and the same design file. indicates it is really a personal preference, such as a developer's own note-taking tool, rather than something this specific codebase depends on — project scope means every teammate and every session in this repo inherits it, whether they want it or not. - State plainly which servers grant filesystem or network access beyond this repository, since that is the specific category of MCP tool access most worth a second look before approval. OUTPUT The .mcp.json file, the .env.example additions, and the per-server trust notes, in that order.
Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
A .mcp.json file checked into a repository is, functionally, a standing grant of tool-calling access to every future session opened against that repo, and Claude Code's own approval prompt on first load exists precisely because that grant is consequential enough to require a conscious decision rather than an inherited default nobody actually reviewed — this prompt's per-server trust note is what makes that one-time approval prompt meaningful instead of a formality clicked past out of habit. The dollar-brace substitution requirement is not a style preference, it is the difference between a config file safe to commit and one that is a credential leak the moment it is pushed, since a literal secret written into .mcp.json does not just risk exposure today, it persists in git history even after a later commit removes the line, which is exactly the kind of mistake that is trivial to avoid at authoring time and expensive to undo afterward. Distinguishing project scope from user scope matters because the two have genuinely different blast radii: a project-scoped server is inherited by every teammate and every session opened against this specific repository regardless of whether any individual developer wants it, while a user-scoped server only affects the one person who configured it, and treating a personal convenience tool as though it belongs to the whole team's shared configuration expands everyone's trust surface for a benefit only one person is using. Requiring a concrete justification per server, rather than accepting 'might be useful' as sufficient, targets the specific way tool sprawl accumulates in shared config files — each individual addition looks reasonable in isolation, and only in aggregate does a repository end up with several MCP servers nobody currently uses but everyone's session still loads and implicitly trusts. Flagging a server present in the existing file but absent from the current needs list catches exactly the same drift a stale CLAUDE.md fact would, applied to tool access instead of documentation: an unused grant left in place is not neutral, it is unreviewed standing capability that outlives the reason it was added.
Verified against
Claude Code Sonnet 4.6 · 2026-07-20
Changelog
- 2026-07-20 — Initial publish, verified against Claude Code project-scoped .mcp.json (Sonnet 4.6).
Building this for real?
This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
