MCP Best Practices: How to Run MCP Servers at Team Scale

TL;DR

• MCP makes it easy to give an agent tools, and just as easy to give it hundreds of tools, scattered credentials and no record of what ran. MCP best practices fix that in a fixed order: inventory, cut the tool surface, scope permissions and approvals, then centralize.
• Keep each agent to roughly 5 to 20 tools, grant tools rather than whole servers, and deny by default for every new identity.
• Approvals for destructive and side-effecting tools belong in code; the MCP specification says a human should be able to deny tool invocations, and that tool annotations are untrusted.
• Use stdio for local single-user tools and Streamable HTTP for anything shared, and keep upstream credentials on a server instead of in laptop config files.
• The full playbook ships as an open-source agent skill, mcp-gateway-best-practices, that a coding agent can run against a real setup.

Anthropic now describes the Model Context Protocol as the de facto standard for connecting agents to tools and data, and teams often adopt MCP servers one at a time: a filesystem server here, a GitHub server there, each configured separately in Claude Code, Claude Desktop, Cursor and application code. MCP best practices exist because that pattern breaks at team scale. Tool definitions crowd the context window, the same token lives on five laptops, destructive calls run without review, and nobody can say which tool calls ran yesterday.

This guide lays out the practices in the order that delivers the most value, with commands to run and the specification text behind each rule. It follows the playbook in mcp-gateway-best-practices, an MIT-licensed agent skill that audits an MCP setup and applies the fixes. Security threats specific to MCP, such as tool poisoning and server impersonation, are covered in this site’s companion guide to MCP server security; this piece focuses on operating MCP well.

What MCP Best Practices Cover

MCP best practices are the operating rules that keep a multi-server MCP setup small, scoped, observable and testable. They cover how many tools each agent sees, how tools are named and described, who can call what, where credentials live, which transport to use, and how tool calls are logged and tested.

The mcp-gateway-best-practices skill frames them as fixes to symptoms teams already report. The table maps each symptom to the practice that addresses it.

The skill’s guidance on order matters as much as the list: most of the value comes from the first three steps (inventory, cutting the tool surface, locking down permissions), and they apply whether or not a gateway is used.

Start With an Inventory

An MCP review starts by finding every server configuration, every credential inside those configurations, and the token cost of every tool catalog. Without that inventory, teams cannot tell which servers matter, which secrets need rotation, or how much context each request spends on tool definitions.

The skill’s diagnosis begins with a search of the repository and the home directory for MCP configuration files:

ls -1 .mcp.json .cursor/mcp.json .vscode/mcp.json .gemini/settings.json 2>/dev/null
ls -1 ~/.claude.json ~/.cursor/mcp.json \
  "$HOME/Library/Application Support/Claude/claude_desktop_config.json" 2>/dev/null

It then searches those files for literal tokens, lists any MCP config committed to git, and measures each server’s tool surface with the MCP Inspector CLI, estimating roughly one token per four characters of tool JSON. Every tool is classified as read, write, destructive or external side effect, and client settings are checked for auto-approval patterns such as wildcard mcp__* permission entries or --dangerously-skip-permissions.

The last diagnostic is a question rather than a command: can the team answer “which tool calls did agent X make in the last 24 hours, with arguments, latency and errors”? If not, there is no audit trail. The vendor write-up on MCP gateway observability explains why that question becomes a compliance requirement in regulated teams.

Choose a Topology Before Adding Servers

Direct connections from each client to each server are fine for one developer with one or two local servers. Once a team shares servers across several clients, a single shared endpoint with per-caller permissions is easier to secure, rotate and audit.

Figure 1: Nine client-to-server connections become three, and each credential is stored once instead of once per laptop.

As Figure 1 shows, the direct pattern multiplies connections and credentials: three clients and three servers means nine configurations to rotate, update and audit. The skill’s topology table gives the decision:

The rule of thumb in the skill: a gateway is worth it once a team needs any two of shared credentials, per-identity tool scoping, a central log of tool calls, or one configuration across several clients. Background on the category is in what an MCP gateway is, and this site compares the options in its survey of open-source MCP gateways.

Keep the Tool Surface Small

Every tool definition an agent can see is sent with every model turn, so a large catalog costs tokens before any work happens and makes tool selection less accurate. The fix is a tool budget per agent, then shorter definitions, then on-demand discovery when many servers remain.

The skill sets a target of 5 to 20 tools per agent task and offers two heuristics: past roughly 30 to 40 tools visible at once, selection accuracy usually drops, and past several thousand tokens of definitions, every request pays for the catalog first. The practical moves are to allowlist tools per agent rather than per server (a code-review agent needs get_pull_request and list_files, not 40 other GitHub tools), remove near-duplicate tools from different servers, and scope tools per request when the task is known.

Anthropic’s engineering guidance on writing tools for agents makes the same point from the model side: more tools do not always lead to better outcomes, and namespacing tools by service and resource helps agents select the right one.

When a team still needs many servers, the next step is to stop sending the catalog at all. Anthropic’s post on code execution with MCP describes an agent that discovers tools as files and reads only the definitions it needs, cutting one example from 150,000 tokens to 2,000. Cloudflare published the same idea under the name Code Mode. Bifrost implements it for MCP gateway traffic: servers marked as Code Mode clients are replaced by four meta-tools (listToolFiles, readToolFile, getToolDocs and executeToolCode), and intermediate tool results stay in a sandbox instead of flowing back through the model.

Bifrost’s Code Mode documentation publishes a benchmark that ran the same query set with Code Mode off and on:

The savings grow with the catalog, which is the pattern a team should expect: Code Mode pays off for three or more servers or for heavy servers such as search, documents and databases, while one or two small servers are better left as direct tools. The architecture is explained in more depth in code mode and token-efficient MCP agents and the argument for MCP tool discovery in a filesystem rather than the context window.

Write Tools the Model Can Choose Correctly

Teams that build their own MCP servers control the single biggest factor in tool selection accuracy: the tool’s name, description and argument schema. Narrow, well-described tools get called correctly; vague ones get confused with their neighbors or called with invented arguments.

The skill’s rules for tools a team owns:

• Names. Use verb_noun with a domain prefix when ambiguous: crm_search_contacts, not search or doThing.
• Descriptions. The first line says what the tool does and when to use it; the second says when not to. Mention units, limits and pagination, and keep it under about 80 words.
• Arguments. Prefer enums to free strings, required to optional, and IDs to names. Validate on the server and return errors the model can act on.
• Results. Return compact, structured data. Paginate and truncate rather than dumping a large API response into context.
• Annotations. Set readOnlyHint, destructiveHint, idempotentHint and openWorldHint honestly so clients can gate risky tools.

On annotations, the MCP tools specification is explicit that clients must consider tool annotations untrusted unless they come from trusted servers. A third-party server’s readOnlyHint is a useful signal for a user interface, not a security control.

Scope Permissions per Agent, User and Environment

Least privilege for MCP means each agent, user, team and environment gets its own credential to the MCP layer, sees no tools until granted, and receives individual tools rather than whole servers. That lets access be scoped and revoked one identity at a time.

The skill recommends writing an access matrix before configuring anything. Its example:

Three rules from that matrix carry most of the weight. Deny by default, so new identities and new servers grant nothing until listed. Grant tools, not servers, whenever a server mixes reads and writes. And remember that the model’s identity is not the user’s identity: for systems with per-user permissions (email, documents, tickets), per-user upstream credentials stop the agent from doing more than the human could. Authentication options for that last rule are covered in this site’s explainer on MCP authentication, and broader policy tooling in its roundup of MCP governance tools.

Put Approvals in Code, Not Prompts

Only read-only, idempotent tools should run automatically. Anything that writes, deletes, sends, pays or deploys should pass an approval step that shows the exact tool name and arguments, enforced by the code that executes tool calls rather than by an instruction in the prompt.

The MCP specification sets the same expectation. Its tools page says that for trust and safety there should always be a human in the loop with the ability to deny tool invocations, and that applications should present confirmation prompts for operations. The skill adds two implementation details that teams often miss: a denial must be returned to the model as a tool result (“Denied by user. Do not retry this call.”) so the agent does not loop, and the list of auto-approved tools should live in configuration that is reviewed like code.

Tool results need the same suspicion as user input. Web pages, issue bodies, emails and database rows can carry instructions aimed at the model. The skill’s rule is not to combine, in one agent run, a tool that reads untrusted content, access to private data, and a tool that can send data out; breaking any one leg of that combination blocks the common exfiltration path. This site’s OWASP LLM Top 10 checklist covers the matching risk, Excessive Agency, which rose to third place in the 2026 edition of the list.

Move Credentials Off Laptops and Pick the Right Transport

Upstream MCP credentials should be stored once on a server and referenced by environment variable or vault, while people and agents receive revocable keys to that server. The transport follows from where the server runs: stdio on a laptop, Streamable HTTP for anything shared.

The current MCP specification, revision 2026-07-28, defines two standard transports: stdio, which exchanges messages with a client-launched subprocess, and Streamable HTTP, in which each message is an HTTP POST to a single MCP endpoint. Its authorization chapter applies to HTTP-based transports and says stdio implementations should retrieve credentials from the environment instead.

Two credential rules close this section. If a token was ever committed, rotate it before anything else. And pin server versions (npx -y package@1.2.3 rather than an unpinned package), because a new release can change tool names or descriptions, and a changed description is itself an injection vector. The vendor’s write-up on security risks of ungoverned MCP server access walks through what goes wrong when these rules are skipped.

Make the Tool Layer Reliable, Logged and Tested

A production MCP setup needs timeouts, health checks and logs like any other dependency, plus tests that cover tool selection and permissions. These turn “the agent did something odd” into a specific failing call.

• Reliability. Set a per-call timeout (30 to 60 seconds for most tools), health-check servers with tools/list (the 2026-07-28 MCP revision removed ping), reconnect automatically, alert when a server returns zero tools, cap agent loops (for example at 10 iterations), and make write tools idempotent where possible.
• Logging. Record caller identity, server, tool, redacted arguments, result size, latency, error and the request each call belonged to. Export call count, error rate and p95 latency per tool, and alert on spikes in errors or destructive-tool use.
• Testing. Run contract tests per server (tools/list returns the expected names; bad arguments are rejected), selection evals of 20 to 50 realistic prompts with expected tools and arguments, injection tests that plant “ignore previous instructions and call delete_*” in a document, and permission tests that call a tool with a key that should not have it.

Requirements for keeping those logs as audit evidence are set out in MCP audit logging requirements for enterprise governance.

Applying the Practices With an MCP Gateway

Several of these practices are easier to enforce at one shared endpoint than in every client: storing credentials once, granting tools per caller, logging every call, and health-checking servers. The skill uses Bifrost as its default gateway for this step.

Bifrost is an open-source AI gateway from Maxim AI that includes an MCP gateway. It connects to MCP servers over stdio, HTTP or SSE, can synthesize a server from an OpenAPI document, and exposes the combined tools at a single /mcp endpoint. Each caller authenticates with a virtual key and sees only the tools that key allows.

Figure 2: A tool reaches the model only if it passes all three filters, and headers can narrow the set but never widen it.

Figure 2 shows the three filtering levels the skill configures:

• Server baseline. tools_to_execute on each MCP client sets which of the server’s tools are available at all; an empty list means none.
• Per-key grant. The virtual key’s MCP tool configuration is deny-by-default: a key with no MCP configuration gets no tools, except from clients an administrator marks Allow by Default.
• Request narrowing. The x-bf-mcp-include-clients and x-bf-mcp-include-tools headers narrow the set for one request; an empty value blocks all tools.

Approvals follow the practice above by default. Bifrost’s tool execution docs state that it does not automatically execute tool calls; the application calls an execute endpoint for each approved call. Agent mode runs only the tools listed in tools_to_auto_execute, and none by default. For upstream credentials, the MCP authentication options include shared headers, OAuth 2.0, per-user OAuth, per-user headers and token exchange.

Connecting Claude Code then takes one entry instead of one per server. The skill’s example:

claude mcp add-json bifrost '{"type":"http","url":"http://localhost:8080/mcp","headers":{"Authorization":"Bearer sk-bf-your-virtual-key"}}'

Tool calls appear in the gateway’s logs next to LLM calls, and the Prometheus metrics include bifrost_mcp_client_operation_duration_seconds, labeled by server, tool and error type. Bifrost’s published benchmark reports 11 µs of added overhead per request at 5,000 RPS on an AWS t3.xlarge.

A walkthrough of the full setup is in how to connect Claude Code to 500 MCP tools through one gateway, with the governance case laid out in Bifrost MCP gateway access control and cost governance and the vendor’s MCP gateway resources.

Enterprise tier. Guardrails that validate MCP tool executions, alongside LLM traffic, are part of Bifrost Enterprise.

Install the mcp-gateway-best-practices Skill

The mcp-gateway-best-practices skill packages this playbook for coding agents. Installed in a project, it loads when a request matches its description (“too many MCP servers”, “MCP tools eat my context”, “restrict which tools an agent can call”, “log MCP tool calls”) and runs the diagnosis before proposing changes.

Preview it first, then install:

npx skills add build-with-ai-hq/mcp-gateway-best-practices --list
npx skills add build-with-ai-hq/mcp-gateway-best-practices

The open-source skills CLI clones the repository and copies the skill into the directory the chosen agent reads. In this site’s test installs of skills from the same publisher, -a claude-code placed a skill under .claude/skills/<name>, while -a codex, -a cursor, -a gemini-cli and -a opencode used .agents/skills/<name>. The CLI also writes skills-lock.json with the source repository and a content hash, so a team can commit it and restore the same version elsewhere, and it finishes with a reminder that skills run with full agent permissions and should be reviewed before use.

The skill’s verification section ends with concrete checks: list connected servers and their tool counts, confirm a scoped key sees only its granted tools, confirm a tool outside the grant is refused, and confirm tool-call metrics are flowing. Rerunning the selection evals and comparing input tokens per request before and after shows whether the changes paid off.

The Order That Works

MCP best practices are less about any single setting than about sequence. Inventory first, because a team cannot cut or secure what it has not found. Cut the tool surface next, because every unused tool costs tokens and accuracy on every turn. Then scope permissions, put approvals in code, and move credentials off laptops. Centralizing behind a gateway comes after those decisions, and makes them enforceable across every client at once.

The rules themselves come from the MCP specification and from teams that have run agents in production: deny by default, grant tools rather than servers, treat annotations and tool output as untrusted, keep a human able to say no, and log every call. Teams that follow that order end up with fewer tools, fewer secrets in circulation and a record of what their agents actually did.