MCP Server Configuration & Scoping

Core

Integrate MCP servers into Claude Code and agent workflows · Difficulty 3/5

mcpconfigurationintegrationcredentials

Prerequisites

Model Context Protocol (MCP) provides a standardized way to connect Claude to external tools and data sources.

MCP Server Scoping

Scope	Config File	Use Case	Version Controlled

|-------|------------|----------|-------------------|

Project	`.mcp.json`	Shared team tooling	Yes
User	`~/.claude.json`	Personal/experimental servers	No

Tools from all configured MCP servers are discovered at connection time and available simultaneously to the agent.

Project-Scoped Configuration

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Environment variable expansion (${GITHUB_TOKEN}) keeps credentials out of version control while providing a single source of truth for team configuration.

MCP Resources

MCP resources expose content catalogs (issue summaries, documentation hierarchies, database schemas) to give agents visibility into available data without requiring exploratory tool calls. This reduces unnecessary tool invocations and improves agent efficiency.

Best Practices

Community servers first: Use existing community MCP servers for standard integrations (GitHub, Jira, Slack). Reserve custom servers for team-specific workflows.

Enhance descriptions: MCP tool descriptions should explain capabilities and outputs in detail. Vague descriptions cause the agent to prefer built-in tools (like Grep) over more capable MCP tools.

Never commit secrets: Always use environment variable expansion for tokens and credentials.

User scope for experiments: Personal or experimental servers go in ~/.claude.json to avoid polluting the team config.

Key Takeaways

✓Use project-scoped .mcp.json for team tools, user-scoped ~/.claude.json for personal tools
✓Environment variable expansion (${TOKEN}) keeps credentials out of version control
✓Enhance MCP tool descriptions to prevent agents from preferring built-in tools over more capable MCP tools
✓Use MCP resources to expose content catalogs and reduce exploratory tool calls

Glossary Terms

Model Context Protocol (MCP)

An open standard protocol for connecting Claude to external tools and data sources. Defines a client-server architecture where MCP servers expose tools, resources, and prompts that Claude clients can discover and use. Supports project-scoped (.mcp.json) and user-scoped configurations.

Related Concepts

Built-in Claude Code Tools

Grep searches file contents; Glob finds files by name pattern -- don't confuse them

Tool Distribution & Least Privilege

Each agent should have only the tools needed for its specific role (4-5 tools, not 18)

Test Yourself1 of 2

Your team wants to add a GitHub MCP server for PR lookups. Each developer has their own GitHub personal access token. You want consistent tooling without committing credentials. What's the most effective configuration approach?