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 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 makes the intended boundary reviewable. Enforce it separately through narrow service credentials and Claude Code permissions; a Markdown note cannot restrict a token that already has broad access.

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.

Test one denied action before rollout

Use synthetic data in a test service. First confirm the one required read succeeds. Then attempt a write with the same credentials and require the service or runtime to deny it. Stop the MCP server and confirm the workflow reports that evidence is unavailable rather than inventing a result. Record the actual tool names and outcomes in the connector review note. A successful read alone does not prove least privilege.

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.

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.

Editorial update

Updated 20 September 2026: added an explicit permission check and connector failure exercise.