Claude Code MCP Integration Contract

Treat the Claude Code MCP documentation as a contract source, not just a setup page. For a Claude Code team, the hard part is rarely adding one MCP server. The hard part is deciding what that server may touch, who owns it, and how another engineer can review the agent’s work without replaying the whole chat.

I would use the official docs to write one small integration note per server. That note belongs with your Team conventions, and it is a good exercise for a Claude Code workshop because it forces the team to name the workflow before adding more context.

Start with the server’s job

An MCP server should earn its place by serving one workflow. “Connect GitHub” is too broad. “Let Claude Code inspect pull request checks and linked issues during review” is specific enough to reason about.

A concrete workflow is PR triage after CI fails. Claude Code may need to read the pull request, the failing check output, the changed files, and the related issue. It does not automatically need permission to merge the PR, edit labels, or post comments.

That boundary matters because MCP makes outside systems available inside the coding session. More access can save time, but it also creates more to audit.

Turn the docs into a team contract

Use the docs to identify the configuration surface, then write down the team decision beside it. The contract should be short enough that someone will actually read it during review.

Use this procedure for each MCP server:

1. Name the workflow the server supports.
2. Name the external system it connects to.
3. Record the minimum access needed for the workflow.
4. Decide which actions Claude Code may suggest, and which actions a human must perform.
5. Assign an owner for credentials, rotation, and server updates.
6. Define the evidence a reviewer should see before trusting the result.

If a repository uses CLAUDE.md, keep the integration note there only when it changes day-to-day agent behavior in that repo. Do not turn repository memory into a dump of connection details. Put durable rules close to the repo, and keep secrets and operational setup in managed configuration.

Keep permissions tied to review evidence

The permission decision should be written in terms a reviewer can check. “Read-only GitHub access for PR metadata and checks” is reviewable. “GitHub access” is not.

In our Delegate, Review, Own method, this belongs in the Review step: decide what evidence the agent must leave behind before a person accepts the change. For related security review habits, pair this with Claude Code Security Review Receipts, especially when an MCP server can see private code, tickets, documents, or deployment data.

There is a tradeoff here. A narrower server scope may require the developer to paste one missing link or run one extra command. That is usually cheaper than giving every session broad access and trying to reconstruct what happened later.

Use skills for repeatable integration work

When the same MCP-backed workflow appears in several repos, move the repeatable instructions into a Claude skill. Keep the MCP server responsible for access to the outside system, and keep the skill responsible for the way your team uses that access.

For example, a PR review skill can tell Claude Code to inspect failing checks, summarize the suspected cause, list the files it used, and stop before posting anything externally. The MCP server provides the data. The skill shapes the work.

This separation keeps the integration easier to maintain. Server configuration changes when access changes. Skill instructions change when the workflow changes.

Paste this MCP review note

Use this as the copyable artifact for a new or existing MCP server. I would put it in the PR that introduces the server, or in the repo’s engineering docs if the server is shared across projects.

## MCP server review note

Server name:
External system:
Team owner:
Workflow supported:

Allowed use:
- Read:
- Write:
- Human-only actions:

Review evidence required:
- What Claude Code must cite or summarize:
- Files, tickets, checks, or documents the reviewer should see:
- Commands or logs the reviewer should not have to infer from chat:

Credential and operations notes:
- Where configuration is managed:
- Rotation owner:
- Failure mode if the server is unavailable:

Repo behavior:
- Does this change CLAUDE.md or another team convention file?
- Does this require a skill, slash command, or hook update?

Do not fill this with implementation trivia. The note is there to make access, ownership, and review plain.

Further reading

• Claude Code docs
• Claude Code skills
• MCP specification

Next step

Pick one MCP server already in use and fill in the review note before adding another integration.

If you use the Delegate, Review, Own method, this is a Design habit: delegate option mapping and pattern exploration, review the interfaces and tradeoffs, and keep ownership of architecture and contracts.