MCP Servers Configuration Reference

This document provides comprehensive reference documentation for configuring MCP (Model Context Protocol) servers within the 1MCP Agent.

Overview

The 1MCP Agent manages multiple backend MCP servers through a JSON configuration file. Each server is defined in the mcpServers section with specific properties that control its behavior, transport method, and environment.

---

Configuration File Structure

JSON File Structure

The agent uses a JSON file (e.g., mcp.json) to define backend servers and their settings.

{
  "mcpServers": {
    // Server definitions
  }
}

Default Locations

• macOS: ~/.config/1mcp/mcp.json
• Linux: ~/.config/1mcp/mcp.json
• Windows: %APPDATA%\1mcp\mcp.json

Config Directory Override

The agent supports overriding the entire config directory location, which affects where the configuration file, backups, and other related files are stored.

Default Locations:

• macOS: ~/.config/1mcp/
• Linux: ~/.config/1mcp/
• Windows: %APPDATA%\1mcp\

Override Methods:

1. Command Line Flag:

   npx -y @1mcp/agent --config-dir /custom/config/path

2. Environment Variable:

   ONE_MCP_CONFIG_DIR=/custom/config/path npx -y @1mcp/agent

When you override the config directory, the agent will:

• Look for mcp.json in the specified directory
• Store backups in a backups subdirectory
• Store presets and other configuration files in the specified directory

Example:

# Use a project-specific config directory
npx -y @1mcp/agent --config-dir ./project-config

This creates a self-contained configuration setup for projects that need isolated configurations.

---

MCP Servers Configuration

mcpServers Section

This is a dictionary of all the backend MCP servers the agent will manage.

• Key: A unique, human-readable name for the server (e.g., my-filesystem).
• Value: A server configuration object.

Server Properties

Common Properties:

• transport (string, optional): stdio or http. Defaults to stdio if command is present, http if url is present.
• tags (array of strings, required): Tags for routing and access control.
• timeout (number, optional): Connection timeout in milliseconds.
• enabled (boolean, optional): Set to false to disable the server. Defaults to true.

HTTP Transport Properties:

• url (string, required for http): The URL for the remote MCP server.

Stdio Transport Properties:

• command (string, required for stdio): The command to execute.
• args (array of strings, optional): Arguments for the command.
• cwd (string, optional): Working directory for the process.
• env (object or array, optional): Environment variables. Can be an object {"KEY": "value"} or array ["KEY=value", "PATH"].
• inheritParentEnv (boolean, optional): Inherit environment variables from parent process. Defaults to false.
• envFilter (array of strings, optional): Patterns for filtering inherited environment variables. Supports * wildcards and ! for exclusion.
• restartOnExit (boolean, optional): Automatically restart the process when it exits. Defaults to false.
• maxRestarts (number, optional): Maximum number of restart attempts. If not specified, unlimited restarts are allowed.
• restartDelay (number, optional): Delay in milliseconds between restart attempts. Defaults to 1000 (1 second).

Configuration Examples

Basic Configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "/data"],
      "tags": ["files", "local-data"]
    },
    "remote-api": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "tags": ["api", "prod"],
      "timeout": 15000
    }
  }
}

Enhanced Stdio Configuration:

{
  "mcpServers": {
    "enhanced-server": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "/app",
      "inheritParentEnv": true,
      "envFilter": ["PATH", "HOME", "NODE_*", "!SECRET_*", "!BASH_FUNC_*"],
      "env": {
        "NODE_ENV": "production",
        "API_KEY": "${MCP_API_KEY}",
        "DEBUG": "false"
      },
      "restartOnExit": true,
      "maxRestarts": 5,
      "restartDelay": 2000,
      "tags": ["production", "api"],
      "timeout": 30000
    }
  }
}

Array Environment Format:

{
  "mcpServers": {
    "array-env-server": {
      "command": "python",
      "args": ["server.py"],
      "env": ["PATH", "NODE_ENV=production", "API_KEY=${SECRET_KEY}"],
      "tags": ["python", "api"]
    }
  }
}

---

Advanced Environment Management

Environment Variable Substitution

Use ${VARIABLE_NAME} syntax in your configuration to substitute environment variables at runtime:

{
  "mcpServers": {
    "dynamic-server": {
      "command": "${SERVER_COMMAND}",
      "args": ["--port", "${SERVER_PORT}"],
      "env": {
        "API_KEY": "${SECRET_API_KEY}",
        "DATABASE_URL": "${DB_CONNECTION_STRING}"
      },
      "tags": ["dynamic"]
    }
  }
}

Environment Inheritance and Filtering

Inherit Parent Environment: Set inheritParentEnv: true to inherit environment variables from the parent process:

{
  "inheritParentEnv": true
}

Environment Filtering: Use envFilter to control which variables are inherited using pattern matching:

{
  "inheritParentEnv": true,
  "envFilter": [
    "PATH", // Allow PATH variable
    "HOME", // Allow HOME variable
    "NODE_*", // Allow all NODE_* variables
    "NPM_*", // Allow all NPM_* variables
    "!SECRET_*", // Block all SECRET_* variables
    "!BASH_FUNC_*" // Block bash function definitions
  ]
}

Filter Patterns:

• VARIABLE_NAME: Include specific variable
• PREFIX_*: Include all variables starting with PREFIX_
• !VARIABLE_NAME: Exclude specific variable
• !PREFIX_*: Exclude all variables starting with PREFIX_

Flexible Environment Formats

Object Format (Traditional):

{
  "env": {
    "NODE_ENV": "production",
    "DEBUG": "false",
    "API_TIMEOUT": "30000"
  }
}

Array Format (Docker-style):

{
  "env": [
    "NODE_ENV=production",
    "DEBUG=false",
    "PATH", // Inherit PATH from parent
    "API_TIMEOUT=${TIMEOUT_VALUE}"
  ]
}

---

Process Management

Automatic Restart

Enable automatic process restart when the server exits unexpectedly:

{
  "restartOnExit": true,
  "maxRestarts": 5,
  "restartDelay": 2000
}

Restart Configuration Options:

• restartOnExit: Enable automatic restart functionality
• maxRestarts: Limit restart attempts (omit for unlimited restarts)
• restartDelay: Milliseconds to wait between restart attempts (default: 1000ms)

Working Directory

Set a custom working directory for the process:

{
  "cwd": "/path/to/server/directory"
}

---

Complete Configuration Example

{
  "mcpServers": {
    "production-server": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/app",

      // Environment inheritance with security filtering
      "inheritParentEnv": true,
      "envFilter": [
        "PATH",
        "HOME",
        "USER", // Basic system vars
        "NODE_*",
        "NPM_*", // Node.js related
        "!SECRET_*",
        "!KEY_*", // Block secrets
        "!BASH_FUNC_*" // Block functions
      ],

      // Custom environment with substitution
      "env": {
        "NODE_ENV": "production",
        "API_KEY": "${PROD_API_KEY}",
        "DB_URL": "${DATABASE_CONNECTION}",
        "LOG_LEVEL": "info"
      },

      // Process management
      "restartOnExit": true,
      "maxRestarts": 3,
      "restartDelay": 1500,

      // Standard MCP properties
      "tags": ["production", "api"],
      "timeout": 30000
    }
  }
}

---

Hot-Reloading

The agent supports hot-reloading of the configuration file. If you modify the JSON file while the agent is running, it will automatically apply the new configuration without a restart.

---

See Also

• Configuration Deep Dive - CLI flags and environment variables
• Serve Command Reference - Command-line usage examples
• Security Guide - Security best practices for MCP servers