Claude Code for Engineering Teams: Setup MCP and Workflow Integration
Claude Code went from 4% of developer usage in May 2025 to 63% by February 2026. Most of that growth happened organically: one engineer tries it, likes it, and word spreads. What doesn't spread is the configuration.
So you end up with configuration drift. Different CLAUDE.md files (or none). Different MCP servers, or none. Different tool permissions. No shared codebase context. Everyone is technically "using Claude Code" and the results vary wildly.
This guide covers the configuration layer: how to turn a scattered set of individual installs into something consistent that the whole team benefits from.
what a managed team setup actually means#
the individual-to-team gap: why configuration drift kills productivity#
An engineer who set up Claude Code properly, with a solid CLAUDE.md, a few MCP servers wired to the tools they actually use, and some custom skills for recurring work, gets genuinely good results. An engineer on the same team who ran the default install and never touched it gets inconsistent, context-thin output.
Both will tell you they're "using Claude Code." The gap between them is large, and it compounds fast across a ten-person team.
73% of engineering teams now use AI coding tools daily, up from 41% in 2025 (Developer Survey 2026, 15,000 developers). The ones getting consistent results treat configuration as a shared concern, not an individual preference.
the three layers that need standardization: context, tools, and behavior#
A properly standardized Claude Code team environment has three layers:
- Context -- What does Claude know about your codebase? (CLAUDE.md)
- Tools -- What can Claude connect to? (MCP servers via .mcp.json and managed-mcp.json)
- Behavior -- What can Claude do and how does it do it? (permissions, skills, enterprise policy)
Most teams that say "we're using Claude Code" have configured layer one partially and haven't touched layers two and three. This guide covers all three.
what you are building toward#
End state: every engineer starts a Claude Code session with the same project context, the same internal tools connected, the same custom skills, and the same permission policy. Configuration lives in the repo and in your MDM system, not scattered across home directories.
step 1: author your CLAUDE.md#
what CLAUDE.md does and where it lives#
CLAUDE.md is a Markdown file that Claude Code reads at session start. It gives Claude persistent knowledge about your project without repeating it every session.
It can live in multiple places, and Claude loads them hierarchically:
- Root CLAUDE.md (
/your-repo/CLAUDE.md) -- loaded for all sessions in this repo - Subdirectory CLAUDE.md -- loaded when Claude Code is working in that directory
- System-wide CLAUDE.md (
~/.claude/CLAUDE.md) -- loaded for all sessions, regardless of project
The root CLAUDE.md checked into your repository is what every engineer inherits automatically. That's the one to get right.
what belongs in a team CLAUDE.md#
Think of it as the context a senior engineer carries in their head on day one. Not everything they know, just what a new person needs to stop making avoidable mistakes.
Architecture overview. How is the system structured? What are the major components and service boundaries? Two to four paragraphs usually covers it.
Directory map. Where do API routes live? Tests? Config? Claude will figure it out by exploring the filesystem, but a map saves it time and gets first-pass results closer to correct.
Coding conventions. What naming conventions does your team use? What patterns are preferred or banned? What linting rules are non-negotiable?
Test requirements. Expected coverage. Where unit vs. integration tests go. What test utilities exist.
Off-limits scope. What should Claude never modify without explicit instruction? Migrations, CI config, vendor code?
Dev workflow. How to run tests. How to start the dev server. What environment variables are required.
how Claude loads CLAUDE.md at session start#
CLAUDE.md content goes into the model's context at initialization, not as a tool call or file read. It's always present in the session without the engineer referencing it.
The implication: keep it focused. Everything in CLAUDE.md consumes context window space on every session. A bloated file that tries to cover every edge case dilutes the signal for everything else. Target 500-1,500 words of genuinely useful context.
practical CLAUDE.md structure for a production engineering team#
# [Project Name] -- CLAUDE.md
## What This Is
[2-3 sentences: what the system does, primary stack, who operates it]
## Architecture
[3-4 paragraphs: key components, service boundaries, data flow]
## Directory Structure
[Annotated directory listing of the important paths]
## Development Standards
- Language/framework conventions
- Naming rules
- Patterns to use / patterns to avoid
## Testing
- How to run tests
- Where unit vs integration tests live
- Required coverage for new code
## Do Not Touch Without Explicit Instruction
- [List specific files, directories, or systems]
## Running Locally
[Commands to start dev server, required env vars, dependencies]step 2: configure project-scoped MCP servers#
MCP server scopes: local, project, and enterprise#
Claude Code has three MCP server configuration scopes:
- Local (user-scoped): Lives in
~/.claude.json. Only affects that engineer. Not committed to the repo. - Project-scoped: Lives in
.mcp.jsonin the project root. Committed to the repo. Applies to everyone working in this project. - Enterprise (managed): Lives in a system-wide
managed-mcp.jsondeployed via MDM. Applies to all Claude Code instances on managed machines.
For team standardization, the project-scoped .mcp.json is the main lever.
how to commit a .mcp.json for shared server config without exposing credentials#
The problem: .mcp.json defines which servers to connect, but MCP servers need credentials to work. You can't commit tokens to the repo.
The fix: commit server configuration (name, command, args) in .mcp.json, and have each engineer add their own credentials in ~/.claude.json under the same server name. Claude Code merges the two at session start: the project-level file provides the server definition, the user-level file provides the auth.
Example .mcp.json (safe to commit):
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
},
"jira": {
"command": "npx",
"args": ["-y", "@company/mcp-jira-server"]
},
"internal-api-docs": {
"command": "node",
"args": ["./tools/mcp-api-docs/server.js"]
}
}
}Each engineer adds their credentials in ~/.claude.json:
{
"mcpServers": {
"github": {
"env": { "GITHUB_TOKEN": "ghp_yourpersonaltoken" }
},
"jira": {
"env": { "JIRA_API_TOKEN": "yourjiratoken" }
}
}
}Server names must match exactly between the two files.
which MCP servers actually matter for engineering teams#
GitHub. Claude can list issues, read PR comments, create branches, and understand what's actively being worked on. Useful for code review and issue-driven development.
Jira or Linear. Claude can read the ticket being worked on, understand the acceptance criteria, and write code that matches the spec. Removes the constant context-switching between ticket and implementation.
Internal API documentation. A custom MCP server that serves your OpenAPI specs gives Claude accurate knowledge of your actual contracts. Without this, it guesses from generic patterns, which is fine until it isn't.
Databases (read-only). A Postgres or MySQL server scoped to a read-only connection lets Claude answer data questions, generate accurate queries, and check that new code fits your actual schema. Keep it read-only.
transport selection: stdio vs. HTTP#
- stdio: The server runs as a child process, communicating over stdin/stdout. Simpler to set up, works locally, no network config needed.
- HTTP (SSE): The server runs on a specific port. Necessary for shared servers, Docker environments, or when multiple Claude Code sessions need to connect to the same instance.
If each engineer runs their own server processes locally, stdio is simpler. If multiple engineers connect to a central server (say, a shared read-only database server), use HTTP.
step 3: build custom skills for recurring workflows#
what skills are: SKILL.md files that become /slash-commands#
Skills are SKILL.md files with YAML frontmatter that Claude Code loads as /slash-commands. An engineer types /pr-description, Claude Code loads the skill's context, and runs the defined workflow.
A minimal skill:
---
name: pr-description
description: Generate a pull request description from the current branch diff
---
Review the changes in the current branch against main. Write a concise PR description covering:
1. What changed and why
2. Key implementation decisions
3. Testing approach
4. Any follow-up items
Format as standard Markdown. Keep the summary under 200 words.how skills load context on demand#
CLAUDE.md is always loaded. Skills load only when invoked. That means you can have a library of 20+ skills without adding any overhead to sessions where they're not used. Build as many as you need.
This also means you can write detailed, context-heavy skills for complex workflows: code review checklists, deployment procedures, architecture decision records. Their cost is zero when they're sitting idle.
what's worth building#
PR description generation. The most used team skill. Takes the diff, formats a structured description. Engineers run it in 5 seconds instead of 5 minutes.
Test scaffolding. Give it a function or class name, it generates a test file with the correct imports, structure, and common edge cases stubbed out. Particularly useful for teams with specific test conventions that Claude doesn't know by default.
Code review checklist. Loads your team's review criteria and runs through the diff against each item. Consistent signal without relying on whoever is reviewing having it memorized.
Deployment checklist. Before merging to main: migrations, config changes, feature flag states, monitoring alerts. Run it once and stop forgetting things.
provisioning org-wide skills on an Enterprise plan#
On Enterprise plans, account Owners can provision skills for the whole organization. They appear automatically for all users without individual setup.
This makes sense for company-wide standards (security review steps, code style enforcement) or onboarding workflows that every new engineer should run. Project-specific skills still live in the repo alongside the CLAUDE.md and .mcp.json.
step 4: lock down permissions#
how Claude Code permission prompts work#
The first time Claude Code tries a new tool or operation type in a session, it asks the engineer for approval. Approved permissions persist for that session, stored in a session file.
For teams, this creates drift: different engineers approve different things, no one tracks what they've approved, and Claude Code's actual capabilities vary person to person.
tool-level allow/deny in settings.json#
Define explicit rules in settings.json to eliminate prompts for expected operations:
{
"tools": {
"allowed": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
"denied": ["WebFetch"]
}
}A settings.json committed to the project root applies to all engineers in that repo. Start conservative at the project level. Broader permissions belong in user-level or enterprise-level config.
enterprise admin controls#
Enterprise accounts add admin-managed policy through two mechanisms:
managed-settings.json -- Deployed via MDM, this overrides individual engineer settings for security-critical policies. Use it for organizational requirements that individual engineers shouldn't be able to change.
managed-mcp.json -- Defines an allowlist and denylist of MCP servers. Engineers can add servers from the allowlist but can't connect to anything on the denylist. This is where you control what external services Claude Code can reach.
MDM deployment paths:
- macOS (Jamf/Kandji):
/Library/Application Support/ClaudeCode/managed-mcp.json - Windows (registry policy):
HKLM\Software\Anthropic\ClaudeCode\
step 5: integrate with CI/CD and shared tooling#
running Claude Code in non-interactive mode for pipeline use cases#
Claude Code supports non-interactive mode for CI/CD:
claude --no-interactive --prompt "Run the full test suite and report failures"Useful for:
- Automated PR descriptions on push
- Test failure analysis with suggested fixes
- Architecture drift detection against CLAUDE.md conventions
- Code review checks on draft PRs
Store the API key as a CI secret. Not in the repo.
how agent team sessions work#
When Claude Code spawns sub-agents (via the Agent tool), each sub-agent loads the same project context: CLAUDE.md, MCP servers, skills. This is why shared configuration matters beyond individual use. Agent sessions run autonomously, and their knowledge of your codebase is exactly what you've put in the shared config, nothing more.
A lead agent can hand off parallel work to teammates: one refactoring a module, another writing tests, another updating docs. The output consistency depends on how well the shared context is defined. If the context is vague, the agents produce inconsistent results even when they complete successfully.
connecting Claude Code to your error monitoring and issue tracker via MCP#
Beyond GitHub, the next highest-value MCP integration for most engineering teams is error monitoring (Sentry, Datadog, Honeycomb) combined with the issue tracker.
With both connected, Claude Code can look up error traces when writing bug fixes, pull ticket context without the engineer switching tabs, and generate issue descriptions directly from code analysis.
Both require custom or community MCP servers. The MCP ecosystem has over 10,000 published servers and 97 million monthly SDK downloads across Python and TypeScript (Anthropic / Linux Foundation, December 2025). Check before building from scratch.
common setup mistakes and how to avoid them#
credentials in .mcp.json committed to the repo#
The most common security mistake. Tokens or passwords in the .mcp.json env block go into version history and are visible to everyone with repo access, including anyone you ever grant access to in the future.
Split the config as described in step 2: server definitions in .mcp.json, credentials in ~/.claude.json. Add ~/.claude.json to your global .gitignore.
CLAUDE.md bloat#
A CLAUDE.md that documents every edge case becomes noise. Claude Code loads the whole file on every session, so low-signal content doesn't just fail to help, it actively degrades results by diluting what matters.
Target 500-1,500 words. If you're documenting something Claude can discover by reading the code, cut it. The file should cover architectural decisions, standards, and workflow rules that aren't obvious from the codebase itself.
over-permissive MCP scopes#
A database server with write access gives Claude Code the ability to modify production data. A GitHub server with admin permissions can merge PRs and modify settings. Start with the minimum scope and expand only when a specific workflow requires it.
For regulated environments, document the specific scope of each MCP server before deploying. You'll need it for compliance review.
skipping the skills layer#
Skills have an unusually good return on time invested. A PR description skill takes 30 minutes to write and saves 5-10 minutes per PR. At 10 PRs per week per engineer, the math compounds quickly. Most teams skip it because it feels optional. It isn't optional if you care about consistent output.
FAQ#
How do you share MCP server configuration across a team without exposing credentials?
Commit the server definitions (command, args, URL) in .mcp.json. Each engineer adds their own credentials in ~/.claude.json under the same server names. Claude Code merges the two at session start. Server names must match exactly.
What is CLAUDE.md and how does Claude use it?
CLAUDE.md is a Markdown file Claude Code reads at session start. It's loaded as background knowledge in the model's context, always present without being explicitly referenced. Teams commit it to the repo root so everyone starts with the same project context.
What is the difference between local and project-scoped MCP servers in Claude Code?
Local servers (defined in ~/.claude.json) only affect the individual engineer. Project-scoped servers (.mcp.json in the repo root) apply to everyone on the project. Enterprise managed servers are deployed via MDM and apply to all machines in the organization.
What permissions does Claude Code Enterprise give admins?
Enterprise admins can deploy managed-mcp.json to control which MCP servers are allowed or blocked, and managed-settings.json to enforce tool-level permissions org-wide. Both deploy via MDM and override individual engineer settings.
How do custom skills work on an Enterprise plan?
Skills are SKILL.md files that become /slash-commands. Individual engineers can create skills locally. Enterprise account Owners can provision skills org-wide: they appear for all users automatically. Project-level skills live in the repo alongside CLAUDE.md.
Does Silverthread Labs help with Claude Code team deployments?
Yes. Reach out through our audit page to discuss your team's setup.
