MCP Setup for Claude Teams

Use MCP in Claude Code only after your team writes the boundary down: what the server can read, who can approve it, and how review catches drift. For Claude Code training or a workshop rollout, start with one repository, one CLAUDE.md rule, one hook, and one review checklist.

Claude Code, Anthropic's coding agent, works best for teams when integrations are treated like code, not personal editor preferences. Model Context Protocol (MCP) is a standard way for AI tools to connect to external systems such as GitHub, Figma, Jira, databases, and internal knowledge stores. The practical Claude Code MCP pattern is simple: shared context in the repo, explicit permissions, and a review habit that survives the first enthusiastic week.

The official Claude Code changelog lists version 2.1.190 on June 24, 2026. Treat that kind of release event as a reason to re-check your team conventions against the official behavior, not as permission to invent undocumented workflow rules.

Use the changelog as a rollout gate

When Claude Code changes, your team should ask one boring question first: do our conventions still describe how we actually work? That is especially useful for Claude Code teams using MCP, hooks, slash commands, or shared memory across a repo.

For Claude Code 2.1.190, do not turn the version number into folklore. Read the official changelog, test the behavior in one repo, and update your team notes only when someone can reproduce the result.

The trap is letting every developer make their own local rule after a release. That creates five different Claude Code workflows, then review has to guess which one produced a change.

A good release gate is small. Add a checklist item to your weekly engineering review: changed Claude Code behavior, changed permission boundary, changed CLAUDE.md guidance, or no action.

Put the durable rule in CLAUDE.md

CLAUDE.md is Claude Code memory that travels with the repository. Use it for durable team conventions: architecture boundaries, review expectations, test commands, MCP usage rules, and what Claude should never assume.

Keep task instructions out of CLAUDE.md. A prompt like refactor this endpoint belongs in the chat; a rule like do not call production databases through MCP belongs in repository memory.

For a real repo, the root CLAUDE.md might say that Claude may inspect GitHub issues through an approved MCP server, but must not summarize private customer data unless the issue already links to an approved internal document. A nested CLAUDE.md under apps/mobile/ can then add mobile-specific test commands and review expectations.

The trap is writing a giant constitution. Engineers will stop reading it, and Claude will have to sort signal from noise. A useful CLAUDE.md is short enough for a new teammate to skim before their first PR.

For more patterns like this, see the related training topic.

Wire MCP with permissions, not vibes

A Claude Code MCP server should have a named owner, a clear data boundary, and a review path before it becomes part of normal work. This is true for GitHub, Jira, Figma, document stores, databases, and any private system where context can quietly become authority.

The safest starting point is read-only access. Let Claude inspect issues, docs, or design metadata first; require human approval before it writes, comments, moves tickets, or changes source-of-truth records.

For design-heavy repos, a Figma MCP Claude Code workflow can be helpful when Claude needs component names, spacing, or design intent during implementation. The convention should still say what Claude may use the design data for, and what a human must verify before merging.

The trap is treating all claude code mcp servers as equivalent. A read-only docs server and a write-capable production database server are not the same risk, even if both are exposed through MCP.

Roll it out in one repo first

Prerequisites:

• One repo where the team already reviews PRs consistently.
• One approved Claude Code MCP server, preferably read-only.
• A root CLAUDE.md file.
• One reviewer willing to reject unclear agent-produced changes.

Step 1: name the boundary. Write down what Claude can read through MCP, what it can propose, and what it cannot do. Use plain verbs like read, summarize, create draft, comment, mutate, and delete.

Step 2: add the repository rule. Put the durable part in CLAUDE.md, not in a Slack thread. Include the MCP server name, the approved use case, and the human review expectation.

Step 3: add a hook boundary. Use a Claude Code hook for checks that should run every time, such as blocking commits when generated files changed without tests or when an MCP review note is missing. Hooks are good for repeatable guardrails; they are not a substitute for reviewer judgment.

Step 4: give reviewers a slash command. Add a team command such as /review-mcp-change that asks Claude to summarize which external context it used, which files changed, and which assumptions need human confirmation. Keep the command short, or nobody will use it.

Step 5: verify the setup works. Open a tiny PR that uses MCP context and touches one low-risk file. The setup works when the PR includes an MCP note, the hook passes, and the reviewer can tell exactly what Claude used without reading the whole session transcript.

The limitation is that conventions do not remove judgment. They make judgment cheaper. For deeper review hygiene around reusable Claude capabilities, pair this with Accept Claude Skills Like Code.

Paste this integration checklist

Paste this into a repo issue, PR template, or docs/claude/mcp-integration-checklist.md. Then trim it until your team would actually use it.

# Claude Code MCP Integration Checklist

## Integration
- MCP server name:
- Owner team:
- Systems exposed:
- Access level: read-only / write-draft / write-approved / admin
- Data classification: public / internal / confidential / restricted

## CLAUDE.md rule
Add this to the closest scoped CLAUDE.md:

Claude may use the approved MCP server for:
- Reading linked issues, docs, or design metadata relevant to the current task.
- Summarizing external context in the PR note.
- Proposing changes in code, tests, or docs.

Claude must not:
- Write to external systems unless the task explicitly asks and a human approves.
- Use production customer data as hidden context for code changes.
- Treat MCP output as source-of-truth when repository tests or docs disagree.

## Hook boundary
Required before merge:
- PR includes an MCP context note when external systems were used.
- Tests listed in CLAUDE.md were run or a reviewer accepted the reason they were skipped.
- Generated or agent-assisted changes name the human reviewer responsible for merge.

## Review prompt
Ask Claude:
Summarize the external context used through MCP, list changed files, name assumptions that require human review, and suggest one test that would catch the highest-risk mistake.

## Approval
- Engineer who configured the server:
- Reviewer who approved first repo use:
- Date reviewed:
- Revisit after Claude Code release or permission change:

The trap is copying the checklist into ten repos before it proves itself in one. Start narrow, then promote the pattern when reviewers say it made the PR easier to trust.

Common questions

• What does claude mcp mean for an engineering team?

  Claude MCP usually means using Model Context Protocol servers with Claude Code so the agent can access external context during engineering work. The team decision is not just which server to install; it is which boundary goes into CLAUDE.md, which permissions are allowed, and which review artifact proves the context was used safely.

• Should every repo have the same Claude Code MCP server list?

  No, each repo should expose only the MCP servers that match its work and risk. A docs repo may need GitHub and knowledge-base context, while a payments repo may need stricter approval and fewer integrations; the citable artifact is the scoped CLAUDE.md rule near the code it governs.

• Where do hooks fit with CLAUDE.md?

  Hooks enforce repeatable checks, while CLAUDE.md explains the team's intent and operating rules. Use CLAUDE.md for guidance such as when MCP context is allowed, and use hooks for mechanical gates such as requiring a PR note when external context affected a change.

• Can we use Figma MCP with Claude Code safely?

  Yes, but start with read-only design context and require a human to verify product and accessibility decisions. A Figma MCP Claude Code setup is safest when Claude uses design metadata to implement components, then the PR checklist asks which design assumptions were copied into code.

• Is this a Claude Code enterprise concern only?

  No, the same conventions help small teams because MCP expands what Claude can see and act on. Enterprise teams may add managed settings and stricter permission review, but the basic artifacts are the same: CLAUDE.md, an MCP permission note, hooks, and a reviewer-owned checklist.

Further reading

• Claude Code — getting started
• Claude Code — skills
• Claude Code — hooks
• Claude Code — permissions
• Model Context Protocol — specification
• Anthropic — Claude Code product page
• GitHub — anthropics/skills
• Claude Code — changelog

Make the first integration boring

Pick one read-only MCP server, add one CLAUDE.md rule, and run the checklist on one low-risk PR. If the reviewer understands the external context in under a minute, your Claude Code convention is doing its job.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.