Plan a Claude Code MCP Configuration
Start narrow: plan a Claude Code MCP configuration around one job, one data source, and one clear permission boundary. MCP gives Claude Code a standard way to reach systems outside the repo, but a working team should not turn on every integration just because the server starts cleanly. In a Claude Code workshop, I would rather see a boring read-only GitHub issue lookup than a clever setup that can mutate tickets, branches, and database state on day one.
As of November 2026, the official Claude Code docs cover MCP configuration alongside advanced setup, managed settings, hooks, and skills. This note is about the team decision around the integration: what the server may read, what it may write, who reviews the output, and when the permission can grow.
Start with one read-only path
The first server should help Claude Code answer a question the repo alone cannot answer. Pick one path where external context reduces guesswork.
A concrete workflow is a GitHub issue to pull request loop. Let Claude Code read the issue, inspect linked PR comments, and compare that with local files before it proposes a change. Do not let it label issues, assign people, merge branches, or edit project metadata in the first pass.
This belongs with Team conventions, because the setup changes how the team works, not just how one developer configures a laptop. The team should treat Claude Code MCP configuration as a reviewable workflow change.
Rolling this out in your team?
We train engineering teams on their own codebase in two days. Claude Code setup, shared rules and review included.
Choose the first server with a decision table
Use a decision table before adding the server. It keeps the discussion practical and stops the config from becoming a pile of personal preferences.
| Choice | Good first answer | Wait until later |
|---|---|---|
| System | GitHub issues, docs, or internal read-only knowledge base | Production database or ticket mutation |
| First task | Read context and summarize constraints | Create, delete, merge, deploy, or assign |
| Permission | Read-only tools only | Broad write access |
| Reviewer | Repo owner or feature lead checks the transcript and diff | No named reviewer |
| Evidence | Link to issue, command output, diff, and final summary | Trust the chat because it sounded right |
For a GitHub-specific setup, I would pair this with Claude Code GitHub MCP Permissions before allowing writes. The important habit is not the table itself. It is forcing the permission to match the first job.
Keep secrets and memory separate
Do not put tokens, server secrets, or permission shortcuts into repository memory. If CLAUDE.md mentions the integration at all, keep it to durable working guidance such as which system is authoritative for issues or architecture notes.
Configuration belongs in the supported Claude Code settings path your team uses. Repository memory should explain conventions, not smuggle credentials or override access rules.
A useful split is simple. The config says what Claude Code can connect to. The repository notes say how the team expects external information to be used.
Add hooks only at hard boundaries
Hooks are worth adding when you need a mechanical boundary, not when you want to document a preference. For example, a hook can require a final summary after a tool call or block a workflow that tries to run a risky command without review.
In our Delegate, Review, Own methodology, this is a Review boundary. Claude Code can gather context and propose work, but the team keeps a visible checkpoint before the integration changes shared state.
Do not use hooks as a substitute for a smaller permission set. If the server can do too much, reduce the server access first.
Paste this MCP rollout record
Use this as the copyable artifact for the pull request, engineering RFC, or team setup note. Keep it short enough that someone will actually update it.
# Claude Code MCP rollout record
Integration owner:
Repository or team:
Date:
## Server
- External system:
- Claude Code config location:
- Environment scope: local / team-managed / other
## First supported workflow
- Task Claude Code may perform:
- Example input:
- Expected output:
- Human reviewer:
## Permission boundary
| Tool or capability | Allowed now | Reason | Review before changing |
|---|---:|---|---|
| Read issue or ticket context | Yes | Needed to understand requested work | Repo owner |
| Read linked docs or comments | Yes | Reduces missing context | Repo owner |
| Create or edit issues | No | Shared project state | Team lead |
| Push branches or merge PRs | No | Code ownership boundary | Maintainer |
| Query production data | No | Data and privacy boundary | Security or platform owner |
## Evidence required in the PR
- Link to the source issue or ticket
- Short summary of external context used
- Diff or command output reviewed by a human
- Note any MCP tool call that failed or returned incomplete data
## Expansion rule
- We only add write access after two reviewed uses of the read-only workflow.
- Each new capability gets its own row in this record.
The expansion rule is deliberately slow. Teams usually need less automation than they think on day one, and more review evidence than they expect once the integration is useful.
Run the rollout once
Pick one repo, one read-only server, and one GitHub issue workflow, then fill in the rollout record before anyone expands permissions. Our hands-on training on Claude Code integrations turns that record into a live review exercise.
Further reading
What to do next
Start from Team conventions.
Train your team on Claude Code
Two days on your team's own repository, onsite or remote, with a written proposal before you commit.
Book a callPrefer to measure first? Take the free team check.