Claude Code MCP team conventions

Good Claude Code team conventions draw three boundaries and keep them visible: one for context, one for action, and one for review. MCP, the Model Context Protocol, is the part of Claude Code (Anthropic's coding agent) that connects external systems like a database, a ticket tracker, or your docs. Most teams do not lose time writing prompts. They lose it at the seams, where one person wires up a connector and nobody else can tell what it touches.

This piece is a short field guide for fitting MCP into how your team already works, so a connector is something a reviewer can read, not something they have to trust.

Decide where each rule lives

Claude Code gives you four homes for team knowledge, and the trick is putting each rule in the right one. Context goes in CLAUDE.md. A repeatable procedure goes in a skill. Anything that must always happen goes in a hook. External access goes through MCP.

When those homes blur, conventions rot. A skill turns into a second memory file, a hook starts carrying fuzzy policy, and CLAUDE.md swells into an encyclopedia nobody reads.

Here is the one-line version worth pasting into Slack: context in CLAUDE.md, procedure in skills, enforcement in hooks, external access through MCP.

Keep CLAUDE.md scoped, not encyclopedic

The fastest way to make CLAUDE.md useless is to put every rule in one file. Policy, process, and one-off exceptions pile up, and the model reads all of it everywhere even when it only matters in one folder.

Keep global rules short. When the rules genuinely change inside a directory, add a nested CLAUDE.md there. Project memory is meant to be layered, so the repo can tell the model what matters here instead of everywhere.

A simple test: if a rule only applies in one folder, do not make every folder carry it.

Write a permission slice for every connector

A connector earns review the moment you can say exactly what it reaches. A permission slice is a short note naming the exact MCP server, the exact tools, and the exact repo path it may touch. That is the whole idea: a connector should reach into what the task needs and nothing more.

The common failure is the wide connector. A server works in one demo, then quietly reaches more systems than the job calls for. A slice closes that gap, because review becomes "does this connector match the task" instead of "can we guess the intent here."

Keep the slice small enough that a reviewer can restate it in one sentence. If they cannot, the connector is doing too much.

Make every MCP change carry a review note

Trust drops fastest when a pull request adds a connector and the description says nothing. The reviewer is left checking the vibe instead of the boundary.

So make the note part of the change, not a comment bolted on afterward. Every PR that adds or changes MCP should answer four questions: what system is connected, what data can move, what permissions were reviewed, and what happens if the connector fails.

That last one matters more than people expect. Test the failure path before you ship: server unavailable, permission denied, stale context. A connector that has no fallback is a surprise waiting for a bad day.

Use this integration checklist

Drop this into your repo as the starter artifact for any Claude Code MCP work. It walks from the task down to the failure test, and it keeps the four homes straight.

# 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.

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. Review then checks whether the connector matches the task, instead of asking the reviewer to guess what the author intended.

• What belongs in an MCP connector review note?

  A connector review note answers four things: what system is connected, what data can move, what permissions were reviewed, and what fallback exists if the connector fails. Put the note inside the change itself, not in a follow-up comment, so the reviewer checks the actual boundary rather than the general feeling of the pull request.

• 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 file, not in memory, where it can load on demand for the next person.

• When should I reach for a hook instead of a prompt?

  Reach for a hook when the rule must always happen, no exceptions. The Claude Code hooks reference shows that hooks fire at specific lifecycle points and run deterministic work: validation, logging, formatting, permission gates, and post-tool checks. Anything fuzzy or judgment-based belongs in CLAUDE.md or a skill, because a conversational memory is the wrong place for a rule you cannot afford to miss.

Start with one connector

Pick the next connector your team plans to ship and write its permission slice and review note before any code runs. Then take it into the team conventions training and check that a fresh reviewer can defend the merge without replaying the chat.