MCP Server Configuration Best Practices

What is MCP configuration?

Model Context Protocol (MCP) is a standard that lets AI models like Claude or GitHub Copilot connect with external tools and services. An MCP server hosts these tools and makes them available to AI clients.

MCP configuration involves creating JSON files that tell clients how to start and connect to these servers. These files define the command to run, arguments to pass, environment variables to set, and which tools to allow.

MCP has three main components:

• MCP client: The AI interface that calls tools (like Claude or VS Code)

• MCP server: The program that hosts and executes tools

• MCP host: The environment where the server runs (your local machine or a cloud instance)

How to structure MCP config files

MCP configuration files use JSON format and follow a specific structure. The main file is typically named .mcp.json and contains information about one or more servers.

Basic file structure

Every MCP config file starts with a top-level mcpServers object. Inside this object, each key represents a named server:

{
  "mcpServers": {
    "my-first-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

The server name (my-first-server in this example) is how the client will identify this server. Choose descriptive names that indicate what the server does, especially if you have multiple servers.

Essential configuration elements

Each server definition needs these key components:

• command: The program to run (like node, python, or npx)

• args: An array of command-line arguments to pass to the program

• env: Environment variables to set when running the command

For example, to run a Python script with an API key:

{
  "mcpServers": {
    "weather-api": {
      "command": "python",
      "args": ["weather_server.py"],
      "env": {
        "WEATHER_API_KEY": "abc123"
      }
    }
  }
}

This tells the client to run python weather_server.py with the environment variable WEATHER_API_KEY set to abc123.

Where to place config files for different scopes

Where you put your MCP config file determines who can use it and when it applies. This is called the "scope" of the configuration.

User scope vs. project scope

MCP configurations can exist at different levels:

• User scope: Settings that apply to all your projects

• Project scope: Settings specific to one project

• Local scope: Settings for your copy of a project

The location of the file determines its scope:

When the same server name appears in multiple scopes, the most specific scope wins. For example, a server defined in your project folder will override one with the same name in your home directory.

Configuration discovery

MCP clients look for configuration files in a specific order:

1. Local IDE-specific files (like .vscode/mcp.json)

2. Project files in the current directory

3. User files in your home directory

Some clients also support automatic discovery of MCP servers configured in other tools. For example, VS Code can find servers you've already set up in Claude Desktop if you enable the discovery setting.

Securing credentials and environment variables

MCP servers often need access to API keys, tokens, or other sensitive information. The env section of your configuration lets you provide these values, but you need to be careful about how you handle them.

Using environment variables safely

Instead of hardcoding credentials in your configuration file, use one of these approaches:

• Input variables: Some clients support prompting for values:

{
  "inputs": [
    {
      "id": "api-key",
      "description": "Enter API Key",
      "password": true
    }
  ],
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

• Environment references: Reference environment variables already set in your system:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${env:MY_API_KEY}"
      }
    }
  }
}

Avoiding credential exposure

Never commit files with hardcoded credentials to version control. Instead:

• Add .mcp.json to your .gitignore file if it contains secrets

• Use a separate .env file (also gitignored) that's loaded at runtime

• Use credential managers built into your operating system

For team projects, create a template file like mcp.example.json that shows the structure without real credentials. Team members can copy this to create their own local configuration.

Adding and managing multiple MCP servers

As your projects grow, you'll likely need multiple MCP servers for different tools or services. Managing them effectively keeps your workflow smooth and organized.

Defining multiple servers

You can define multiple servers in a single configuration file:

{
  "mcpServers": {
    "database-tools": {
      "command": "python",
      "args": ["db_server.py"]
    },
    "api-client": {
      "command": "node",
      "args": ["api_client.js"]
    }
  }
}

This approach works well when the servers are related or used together. Each server runs as a separate process but is managed through the same configuration.

Using different transport types

MCP supports different ways for clients and servers to communicate:

• STDIO transport: For local servers running on your machine

• SSE transport: For remote servers accessed over HTTP/HTTPS

For local servers, STDIO is simpler and more secure:

{
  "mcpServers": {
    "local-server": {
      "type": "stdio",
      "command": "node",
      "args": ["server.js"]
    }
  }
}

For remote servers, use SSE with appropriate headers:

{
  "mcpServers": {
    "remote-server": {
      "type": "sse",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

The transport type affects how the client connects to the server and how they exchange messages.

Troubleshooting common configuration issues

When your MCP server doesn't work as expected, the problem is often in the configuration. Here are some common issues and how to fix them.

Server won't start

If your server doesn't start at all, check these common causes:

• Command not found: The program specified in the command field isn't installed or isn't in your PATH

• Invalid JSON: Your configuration file has syntax errors (missing commas, unmatched brackets)

• File permissions: The script or program doesn't have execute permissions

Most MCP clients provide logs that show the exact command being run and any error messages. In VS Code, you can view these logs by running "MCP: List Servers" and selecting "Show Output" for the problematic server.

Server starts but tools aren't available

If the server starts but no tools appear:

• Missing tool registration: The server isn't properly registering its tools with the MCP client

• Tool filtering: The alwaysAllow field might be restricting which tools are visible

• Schema errors: The tool schemas might have validation errors

Check the server logs for error messages about tool registration or schema validation. The logs often show exactly which part of the schema is causing problems.

Connection timeouts

If the server starts but the client can't connect:

• Slow startup: The server might need more time to initialize

• Network issues: For remote servers, check firewall settings or network connectivity

• Wrong transport: Make sure you're using the correct transport type for your server

You can increase the timeout for slow-starting servers using environment variables like MCP_TIMEOUT=10000 (for 10 seconds).

Optimizing your MCP workflow

Once you have your MCP servers configured, you can streamline your workflow with these techniques.

Command-line management

Most MCP clients provide command-line tools for managing servers:

# Add a new server
claude mcp add my-server -- node server.js

# List all servers
claude mcp list

# Remove a server

These commands let you automate server management or quickly switch between configurations.

IDE integration

VS Code and other IDEs offer integrated MCP support:

• Tool selection directly in the chat interface

• Automatic server discovery and startup

• Visual configuration editors

In VS Code, you can access these features through the Command Palette with commands like "MCP: Add Server" or "MCP: List Servers."

Final thoughts on MCP configuration

MCP configuration is the foundation for connecting AI models with external tools. A well-structured configuration makes your tools more reliable and easier to manage.

Start simple with basic configurations, then expand as you become more familiar with the protocol. Pay attention to security, especially when handling credentials, and use the appropriate scope for each configuration.

As the MCP ecosystem grows, these configuration patterns will likely evolve. Staying familiar with the basics will help you adapt to new features and capabilities.

At Stainless, we're working to make this process smoother by automatically generating MCP servers from OpenAPI specifications. This approach ensures that your MCP tools stay in sync with your API and handle complex schemas correctly.

Frequently asked questions about MCP server config

How do I migrate an existing MCP config to another environment?

Copy the configuration file to the new environment and update any environment-specific values like file paths or hostnames. For credentials, set up new environment variables or input prompts rather than copying sensitive values directly.

What is the difference between MCP client and MCP host?

An MCP client is the application that calls tools (like VS Code or Claude Desktop), while an MCP host is the environment where the server runs (your local machine or a cloud service).

How can I test MCP servers for performance or correctness?

Use the client's built-in tool invocation features to call each tool with test inputs. Check the responses for accuracy and monitor the server logs for errors or performance issues. Some clients also provide specific testing commands.