Claude Code MCP team conventions

Claude Code MCP team conventions come down to three explicit boundaries: one for context, one for action, and one for review. MCP is the Claude Code piece that connects external systems, next to CLAUDE.md for repo memory, skills for procedures, and hooks for deterministic checks. Teams usually lose time at the seams: one person wires an integration, another cannot review it, and the repo fills with private habits. If you are shipping with Claude Code, the question is how to make MCP part of team conventions instead of a one-off setup.

The situation

Counter-thesis: More integrations do not make a team faster. Shared rules do.

The wrong path: We believed broad access and a few shortcuts would keep momentum. We tried loose prompts, ad hoc permissions, and “we’ll document it later”; here is what happened to teams on the floor: reviews got vague, permissions got fuzzy, and nobody could tell whether a change came from repo context, a skill, or an external connector.

Diagnosis: This is the local-optimization trap, and it turns into context drift.

The actual thesis: Claude Code teams need one explicit boundary for context, one for action, and one for review.

Claude Code already gives you the pieces: CLAUDE.md for always-on repo memory, skills for on-demand procedures, hooks for deterministic checks, and MCP for external systems. The work is fitting them together so the thesis stays visible in the repo, in review, and in the workshop.

Where teams get stuck

The wide connector. If you shipped AI code you have hit this: a server works in one demo and then reaches into more systems than the task needs. The fix is a Permission Slice — write down the exact MCP server, the exact tools, and the exact repo path it may touch.

That makes review simpler. The question becomes whether the connector matches the task, not whether the team can guess the intent.

Operational takeaway: keep the slice small enough that a reviewer can restate it in one sentence.

The bloated memory file. If you shipped AI code you have hit this too: policy, process, and exceptions all end up in one giant CLAUDE.md. The fix is a Layered CLAUDE.md — keep global rules short, then add nested project files where the rules change.

This works because Claude Code project memory is meant to be scoped, not encyclopedic. The thesis holds better when the repo tells the model what matters here, not everywhere.

Operational takeaway: if a rule only applies in one folder, do not make every folder carry it.

The skill that became policy. A skill should carry a repeatable procedure, not become a second memory file. The fix is a Procedure Skill — use SKILL.md for steps, checks, and supporting files; keep durable repo facts in CLAUDE.md.

This matters because Claude Code skills load on demand. If the same checklist keeps getting pasted into chat, it belongs in a skill, and the thesis stays cleaner for the next reviewer.

Operational takeaway: move repeatable work out of chat before it becomes tribal knowledge.

The hook that acts like a prompt. Hooks are for lifecycle rules outside the model loop. The fix is a Hook Boundary — use hooks for validation, logging, formatting, permission gates, and post-tool checks.

Claude’s hooks reference says hooks fire at specific lifecycle points and can run shell commands, HTTP endpoints, or prompts. That makes them the right place for deterministic work and the wrong place for fuzzy policy.

Operational takeaway: if the rule must always happen, do not leave it to a conversational memory.

The review note that says nothing. This is where trust drops fastest. The fix is a Connector Review Note — every PR that adds or changes MCP should say what system is connected, what data can move, what permissions were reviewed, and what fallback exists if the connector fails.

That note changes the conversation. Reviewers check the boundary, not the vibe, and the thesis becomes something the team can audit.

Operational takeaway: make the reviewer note part of the change, not a comment after the fact.

A copyable integration checklist

Use this as the team’s starter artifact for Claude Code MCP work:

# MCP integration checklist

- [ ] Name the task the connector supports.
- [ ] List the exact MCP server or servers involved.
- [ ] Record the minimum tools needed.
- [ ] Confirm the data types that may leave the repo.
- [ ] Check whether `CLAUDE.md` already covers the repo rule.
- [ ] Decide whether the procedure belongs in a `SKILL.md` file instead.
- [ ] Add or update a hook for validation, logging, or permission checks.
- [ ] Write the reviewer note: what changed, why it is needed, and what is out of scope.
- [ ] Test the failure path: server unavailable, permission denied, or stale context.
- [ ] Link the change to the team convention page in `/topics/team-conventions`.

If you want one portable rule to repeat in Slack, use this: context in CLAUDE.md, procedure in skills, enforcement in hooks, and external access through MCP.

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.

Practical starter checklist

• Name the Claude Code artifact first: a CLAUDE.md fragment, a Claude skill outline, a hook boundary, an MCP permission note, or a review checklist.
• Write the review checklist before generation starts: scope, owner, tests, rollback.
• Keep the first step small enough that a reviewer can inspect the receipt without replaying the whole chat.

Failure modes to watch

• Named fix: Scope Receipt. Keep one short note that names the Claude Code artifact, the owner, and the files the agent may touch.
• Named fix: Review Gate. Require the reviewer to see the changed rule, checklist, or verification output before approving the work.
• Named fix: Rollback Note. Add the fastest safe undo path next to the change so the team can recover without reconstructing the session.

Synthesis

Synthesis: Treat the agent as a fast implementer behind a receipt gate: it can move quickly only when scope, checks, and ownership are visible.

Best ways to use this research

• Best for: Claude Code teams deciding which CLAUDE.md convention, hook, skill, or MCP boundary to standardize next around “Claude Code MCP team conventions.”
• Best first artifact: turn the named fix into a CLAUDE.md convention, hook checklist, skill note, or review receipt before the next automated run.
• Best comparison angle: compare the workflow against the current Claude Code handoff, hook behavior, and MCP scope; keep the path that leaves the shortest auditable trail.

Common questions

• How do you keep Claude Code MCP reviewable?

  Write a Permission Slice for every connector: the exact MCP server, the exact tools, and the exact repo path it may touch. Keep the slice small enough that a reviewer can restate it in one sentence, so review checks whether the connector matches the task instead of guessing intent.

• What belongs in an MCP connector review note?

  A Connector Review Note says what system is connected, what data can move, what permissions were reviewed, and what fallback exists if the connector fails. Make the note part of the change itself, not a comment after the fact, so reviewers check the boundary instead of the vibe.

• Where do repo rules go: CLAUDE.md, skills, or hooks?

  Context goes in CLAUDE.md, procedure goes in skills, and enforcement goes in hooks; keep CLAUDE.md layered so global rules stay short and nested files carry folder-specific rules. If the same checklist keeps getting pasted into chat, it belongs in a SKILL.md, not in memory.

• What should an MCP integration checklist include?

  Start from the task: name the job the connector supports, list the exact MCP servers, record the minimum tools needed, and confirm which data types may leave the repo. The copyable checklist in this article adds the failure-path test: server unavailable, permission denied, or stale context.

Further reading

• Claude Code docs: en getting started
• Claude Code docs: en skills
• Claude Code docs: en hooks
• Claude Code docs: en permissions
• MCP docs: specification latest
• Claude Code product page
• github.com: anthropics skills

What to do next

Take this into the related training topic and test whether a new reviewer can defend the merge without replaying the chat.