Claude Code Advanced Setup

Advanced configuration for Claude Code including MCP scopes, manual configuration, and troubleshooting.

MCP Scopes

Claude Code supports three configuration scopes for MCP servers:

Scope Location Purpose

local (default)

~/.claude.json (project-specific section)

Personal, current project only

user

~/.claude.json (global section)

Personal, all projects

project

.mcp.json (project root)

Shared with team via git
Both local and user scopes store data in ~/.claude.json, but are differentiated internally. Local-scoped MCPs are associated with a specific project path, while user-scoped MCPs are globally available. See Claude Code MCP documentation for details.

Local (Default)

Local MCPs are personal to you and specific to the current project directory.

# Add MCP at local scope (default)
claude mcp add maven-mail --transport http http://localhost:58080/mcp

Use for:

  • Personal MCP configurations for a specific project

  • Testing and experimentation

  • Configurations you don’t want to share with the team

User-Level (Global)

User-level MCPs are available in all Claude Code sessions, regardless of the working directory.

# Add MCP at user level
claude mcp add --scope user github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

Use for:

  • General-purpose MCPs you always want available

  • MCPs with personal credentials (GitHub token, Atlassian PAT)

  • MCPs that don’t contain sensitive project data

Project-Level

Location: .mcp.json (in project root)

Project-level MCPs are shared with the team via source control.

# Add MCP at project level
claude mcp add --scope project maven-mail --transport http http://localhost:58080/mcp

Use for:

  • Project-specific data sources

  • MCPs with project-specific configurations

  • Shared team configurations (committed to git)

Scope Priority

When the same MCP name exists at multiple levels, precedence is (highest to lowest):

  1. Local (personal, project-specific)

  2. Project (.mcp.json, shared)

  3. User (personal, global)

Security Considerations

Concern Recommendation Scope

Personal API tokens

Store in user-level config

User (--scope user)

Project credentials

Use environment variables or secrets manager

Project (--scope project)

Shared team config

Commit to git (without secrets)

Project (--scope project)

Quick testing

Use local scope (gitignored)

Local (default)

Manual JSON Configuration

Instead of claude mcp add, you can edit configuration files directly.

The ~/.claude.json file has a complex structure managed by Claude Code. Prefer using claude mcp add commands rather than editing it manually.

Project-Level Configuration

File: .mcp.json (in project root)

This is the recommended file for manual editing, as it has a simple structure and is meant to be shared via git:

{
  "mcpServers": {
    "maven-mail": {
      "type": "streamable-http",
      "url": "http://localhost:58080/mcp"
    }
  }
}
Mail MCP uses Streamable HTTP transport to connect to the persistent Docker service. Ensure docker compose up -d is running in the mail-mcp directory.
Do not include personal credentials (tokens, passwords) in .mcp.json since it is committed to git. Use environment variables or add MCPs with credentials to local or user scope instead.

MCP Management Commands

# List all configured MCPs (all scopes)
claude mcp list

# Remove an MCP from local scope (default)
claude mcp remove <name>

# Remove from specific scope
claude mcp remove --scope user <name>
claude mcp remove --scope project <name>
claude mcp remove --scope local <name>

Environment Variables

MCPs can use environment variables for sensitive data:

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

Then set the variable in your shell:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Troubleshooting

MCP Not Connecting

# Check if MCP is listed
claude mcp list

# For Streamable HTTP transport (mail-mcp), verify the server is accessible
curl http://localhost:58080/health

Mail MCP Docker Errors

Ensure Docker services are running:

# Check Docker is running
docker info

# Check mail-mcp services
cd /path/to/mail-mcp
docker compose ps

# View mail-mcp logs
docker compose logs mail-mcp

# Restart if needed
docker compose restart mail-mcp

# For Streamable HTTP transport, verify the server is accessible
curl http://localhost:58080/health

Permission Issues

For macOS/Linux:

# Check file permissions
ls -la ~/.claude.json

# Fix if needed
chmod 600 ~/.claude.json

Debugging MCP Communication

Start Claude Code with verbose logging:

claude --mcp-debug

Related