Configuring MCP Servers for a Team

This guide is for the person on your team who's setting up MCP servers for the whole team — not for one developer's laptop, but for a team of five or ten or fifty. The decisions are different at team scale. Individual developers optimize for "does this MCP work for what I'm doing?" Teams have to optimize for consistency, security, cost, and the fact that any single developer's mistake becomes everyone's mistake.

Why MCP matters for teams

MCP (Model Context Protocol) lets Claude Code read from and act on external systems — your database, your monitoring tool, your issue tracker, your payment provider. Without MCP, Claude works from context you paste in; with MCP, Claude queries fresh state on demand.

For individuals, MCP is convenience. For teams, it's leverage — every developer benefits from every MCP added, and the multiplier compounds. A team of ten with the same five MCP servers configured gets ten times the value from each server. This is the case for standardizing.

It's also the case for standardizing carefully. A team of ten with the same misconfigured MCP server — live-mode credentials committed to git, unrestricted database access, too-broad permission scopes — multiplies risk the same way it multiplies value. The setup discipline this guide covers is designed to make the multiplier positive.

The four decisions

Setting up MCP for a team comes down to four decisions:

1. Scope: which servers should the team share?
2. Config location: team-shared config or per-developer?
3. Auth model: shared credentials or per-developer credentials?
4. Permission scoping: what can each server actually do?

Each is a real decision with real trade-offs. Getting them wrong doesn't necessarily produce visible problems immediately; the problems show up as accumulating incidents over months.

1. Scope: which servers?

The first mistake most teams make is adding too many MCP servers. Every server is context Claude has to load, latency it has to wait for, permissions to manage, and a potential source of confusion when Claude picks the wrong tool. Fewer is better.

Our reference team setup is five servers:

• A database MCP (Postgres, MongoDB, or similar). For query and schema investigation. Most common failure mode: not having this and pasting query results into chat, which is slow and doesn't capture the actual DB state.
• A monitoring MCP (Datadog, Sentry, Grafana). For incident response and performance investigation. Read-only.
• A source control MCP (GitHub or GitLab). For PR context, issue triage, workflow debugging. Most teams already have this via gh CLI; MCP adds structured access.
• A domain-specific MCP for your product's most-integrated service. If you're a SaaS with payments, Stripe. If you're an ecommerce site, Shopify. If you're a marketplace, whatever platform you're on.
• A communication MCP (Slack) for team context. This is optional; skip if it doesn't fit your workflow.

That's five. Not fifteen. Every server past five needs justification: what specific developer workflow does it unblock? For an individual, "it seems useful" is enough justification; for a team, it's not.

Exception: subject-matter-expert developers can install their own additional MCPs beyond the team baseline. If your data engineer needs Snowflake MCP for their specific work, that's fine as long as it's their setup, not the team's shared setup. Team baseline is the shared surface; individuals extend as needed.

2. Config location

The classic question: .claude/settings.json (committed to repo) vs. user-level ~/.claude/settings.json (per-developer)?

Our rule: config in .claude/settings.json, credentials as environment variables referenced from that config. The structure of your MCP setup (which servers, what permissions, what allow-lists) is team policy and should be committed. The specific credentials for each developer to authenticate are personal and should never touch git.

This looks like:

The developer's shell has:

Now the team has consistent config; each developer has their own credentials; the credentials never go through git. Adding a new team member: they clone the repo, they set up their environment variables, they're on the team's MCP setup.

Some teams prefer secret managers (1Password CLI, Doppler, AWS Secrets Manager) over environment variables. The pattern is the same: config committed, credentials externalized.

3. Auth model per server

Two options per server:

• Per-developer credentials. Each developer has their own token/key for the service. Audit trail identifies which developer made which query.
• Shared credentials. One token/key for the team. Simpler; less audit granularity.

Default to per-developer where the service supports it. For services with per-user API keys (GitHub with personal access tokens, Stripe with restricted keys, most SaaS APIs), give each developer their own. Audit trail matters when incidents happen.

Shared credentials only for services where per-user isn't practical or the cost is prohibitive. If your monitoring MCP uses a service-level API key that grants read access, and you can't easily generate per-user keys, shared is fine — but understand that the audit trail is coarser.

Never shared credentials for write access. If a shared credential can create, modify, or delete anything in the target system, don't share it. One misfire from one developer becomes the team's shared incident. Per-developer credentials at least isolate the blast radius.

4. Permission scoping

This is where the biggest gains and biggest incidents both come from.

Default: read-only, narrow scope, allow-list of specific actions. Every deviation from this default needs explicit justification.

Read-only means the credential the MCP uses can't write. For Postgres: a read-only database user. For GitHub: a PAT with read scopes only, no write. For Stripe: a restricted key with read permissions.

Narrow scope means the credential can only access what's necessary. For Postgres: read access to specific databases/schemas, not everything. For GitHub: access to your team's repos, not the org. For Stripe: access to specific resources (customers, charges), not everything.

Allow-list of specific actions means the MCP server config restricts what actions Claude can invoke. Every MCP has some form of this — environment variables like STRIPE_ALLOWED_ACTIONS or configuration flags for enabling specific operations. Use them.

The combination of these three (read-only credential + narrow scope + allow-list) is defense in depth. If any single layer is bypassed, the others catch it.

The reference team setup

Here's what the .claude/settings.json for a reference 10-person SaaS team looks like:

Every server: read-only credential, narrow scope, allow-list of specific things. All credentials are environment variables that each developer sets from their own shell.

Operational patterns

Beyond the initial setup, there are patterns worth institutionalizing:

Pattern 1: quarterly permission audit

Every quarter, review each MCP server's permissions. Common drift: allow-list grew ad-hoc as specific needs came up; some permissions were added and then never removed. Quarterly cleanup: for each MCP, ask "do we still need this specific action?" Remove ones we don't.

Pattern 2: per-MCP on-call owner

Assign each MCP an owner. When something breaks (auth failure, rate limit, unexpected behavior), the owner triages. Prevents "nobody owns the MCP setup" which leads to nobody fixing it. Rotate ownership quarterly.

Pattern 3: MCP changelog

Every change to .claude/settings.json gets a commit message explaining the change. Not just "add sentry MCP" but "add sentry MCP with read-only auth token; grants read access to web/api/worker projects; excluded staff project pending review." Future readers appreciate the reasoning.

Pattern 4: MCP onboarding checklist

For new team members, document the specific credentials they need to generate and where to put them. A one-page checklist saves hours of debugging their first day. Include: for each MCP, the credential type, where to get it, and where to put it.

Rollout plan

If you're starting from scratch, here's the rollout order:

Week 1: Database MCP. Highest utility for typical development. Read-only Postgres user; narrow schema access; committed config; per-developer credentials. Team members onboard themselves during their normal work.

Week 2: Source control MCP. Second most common utility. Per-developer PAT; narrow repo access.

Week 3: Monitoring MCP. Establishes incident-response pattern. Might use shared read-only service token depending on your monitoring tool's capabilities.

Week 4: Domain-specific MCP (Stripe/Shopify/etc.). The one that's specific to your product. Test-mode/sandbox default; per-developer keys.

Week 5 (optional): Communication MCP. Skip if it doesn't fit your workflow. Not every team benefits.

Slow rollout matters. One MCP per week means the team gets used to each one; problems surface individually; you don't overwhelm anyone. Doing them all in one week means the team learns 5 tools simultaneously, which is worse than 5 tools sequentially.

When things go wrong

Six failure modes we've seen (some by hitting them, some by watching others):

Failure 1: Committed credentials. Someone commits their DATABASE_URL to git. Rotate the credential; audit for other exposures; add a git-secrets pre-commit hook. Retrospect: how did this get past code review?

Failure 2: Wrong-mode credentials. Someone puts their live-mode Stripe key in the config that's supposed to be test-mode. Realized when they run a query and get real customer data. Rotate the live-mode key immediately; audit access; fix the config.

Failure 3: Rate limits hit team-wide. Shared credentials for a service with per-account rate limits mean one heavy user impacts the whole team. Fix: switch to per-user credentials. Consequence of shared model.

Failure 4: MCP server version drift. Different developers have different versions of an MCP server (via npm install differences). Behaviors diverge. Fix: pin MCP server versions explicitly in the config; commit lockfile.

Failure 5: Slow MCP hurts every session. A monitoring MCP with high latency slows down every Claude Code session that consults it. Fix: identify slow MCPs; consider disabling them by default and enabling on-demand.

Failure 6: Too many MCPs cause confusion. Claude sometimes picks the wrong tool because too many tools are available. Fix: fewer MCPs; use narrow allow-lists that reduce tool count per server.

What to do next

Concrete next steps:

1. Audit your current MCP setup. Which servers? Which permissions? Which credentials?
2. For each: is it read-only? Narrowly scoped? Allow-listed?
3. For each with any gap: add the missing layer or remove the MCP.
4. Externalize any hardcoded credentials to environment variables.
5. Document the setup in your team's onboarding doc.
6. Set a quarterly reminder for the permission audit.

The setup discipline compounds. A well-configured team MCP setup pays off every session, every day, for every developer. The five hours you spend getting it right saves hundreds of hours over the year.