MCP servers in Claude Code and agents

• Project-level .mcp.json is for shared team tooling; user-level ~/.claude.json is for personal or experimental servers.
• Environment variable expansion (for example ${GITHUB_TOKEN}) keeps credentials out of version control.
• Tools from all configured servers are discovered at connection time and available at the same time.
• MCP resources expose content catalogs (issue summaries, documentation hierarchies, database schemas) to reduce exploratory tool calls.
• Existing community servers are preferred for standard integrations; custom servers are for team-specific workflows.

• Configure shared servers in .mcp.json with environment variable expansion for tokens.
• Configure personal servers in ~/.claude.json.
• Write detailed MCP tool descriptions so the agent does not default to built-in tools like Grep.
• Expose catalogs as resources to give agents visibility without exploration.

• "A private repo makes it safe to commit a token." It does not; use expansion.
• "Resources are just tools by another name." Resources describe available data; tools perform actions.
• "A custom server is always more reliable." For standard integrations it duplicates maintained work.

Personal servers in the shared config, literal secrets in .mcp.json, and capable MCP tools with one-line descriptions.

• 2.1Tool interfaces and descriptions
• 3.1CLAUDE.md hierarchy and organization
• 2.5Built-in tools