Local Configuration Overrides

This document explains the local configuration override system for MCP (Model Context Protocol) servers, specifically the .github/mcp-config.local.json file. This mechanism allows developers to maintain sensitive credentials and machine-specific settings outside of version control while keeping the standard MCP configuration in the repository.

For information about the main MCP configuration file structure, see MCP Configuration File. For broader configuration topics, see Configuration System.

Purpose and Scope

The local configuration override system addresses two primary needs:

1. Sensitive Credentials: Store API tokens, authentication headers, and other secrets that should never be committed to version control
2. Local Development Settings: Maintain machine-specific MCP server configurations that differ from the project's default setup

This system works by allowing multiple MCP configuration files to be loaded simultaneously, with each file contributing additional MCP servers to the Copilot CLI session.

Sources: README.md101-124

Configuration File Location

The local override file must be placed at:

.github/mcp-config.local.json

This file sits alongside the standard configuration file:

.github/
├── mcp-config.json # Committed to version control
└── mcp-config.local.json # Excluded from version control (local only)

Critical Requirement: The local configuration file must be added to .gitignore to prevent accidental commits of sensitive data.

Sources: README.md101-107

File System Structure

Sources: README.md101-107

File Structure

The .github/mcp-config.local.json file uses the identical JSON structure as the standard mcp-config.json file. It contains an mcpServers object defining one or more MCP server configurations:

Key Properties:

Property	Description	Example Values
type	Server connection type	"http", "local"
url	Remote server endpoint	"https://example.com/mcp"
headers	HTTP headers for authentication	{"Authorization": "Bearer token"}
command	Local command to execute	"php", "./vendor/bin/testbench"
args	Command arguments	["artisan", "boost:mcp"]
tools	Available tools from server	["*"] or specific tool names

Sources: README.md111-124

Shell Function Integration

The copilot_mcp shell function provides automatic loading of both standard and local configuration files. This function should be added to .bashrc or .zshrc:

Function Behavior:

• Checks for existence of .github/mcp-config.json
• Checks for existence of .github/mcp-config.local.json
• Appends --additional-mcp-config flags for each existing file
• Passes through all additional command-line arguments
• Gracefully handles missing files

Sources: README.md78-92

Configuration Loading Flow

Sources: README.md78-92

Common Use Cases

Remote MCP Servers with Authentication

The most common use case is connecting to remote MCP servers that require authentication headers:

Multiple Environment-Specific Servers

Different developers may need different development, staging, or testing MCP servers:

Custom Tool Access Restrictions

Override tool availability for specific security requirements:

Sources: README.md109-124

MCP Server Merging Behavior

When multiple configuration files are loaded, Copilot CLI merges all MCP server definitions. Each file can define different servers, and they all become available in the same session:

Important Notes:

• Server names must be unique across all configuration files
• If duplicate server names exist, behavior is undefined
• All servers are initialized when Copilot CLI starts
• Each server operates independently

Sources: README.md78-92 README.md111-124

Manual Loading Without Shell Function

If the copilot_mcp shell function is not configured, both files can be loaded manually:

This syntax can be combined with other Copilot CLI options:

Sources: README.md55-67 README.md82-89

Best Practices

Security Considerations

Practice	Rationale
Always add to .gitignore	Prevents accidental credential commits
Use environment-specific tokens	Different tokens for dev/staging/prod
Rotate credentials regularly	Minimize impact of potential leaks
Use read-only tokens when possible	Limit scope of credential compromise
Document required secrets in README	Help team members configure their local setup

Team Workflow

1. Repository Setup: Commit .github/mcp-config.json with public servers only
2. Local Configuration: Each developer creates their own .github/mcp-config.local.json
3. Documentation: Maintain a template or example file (e.g., mcp-config.local.json.example)
4. Onboarding: Include local configuration setup in developer onboarding process

Configuration Management

Recommended Template Pattern: Commit a sanitized example file to help team members:

Sources: README.md101-124

Relationship to Other Configuration

The local MCP configuration is distinct from other configuration systems in the package:

Configuration File	Purpose	Version Control
.github/mcp-config.json	Standard MCP server definitions	Committed
.github/mcp-config.local.json	Local overrides with secrets	Not committed
boost.json	Laravel Boost features and agents	Committed
testbench.yaml	Orchestra Testbench environment	Committed
.env	Laravel environment variables	Not committed

For details on the standard MCP configuration structure, see MCP Configuration File. For Laravel Boost feature configuration, see Boost Configuration.

Sources: README.md101-124