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. Shared defaults can be defined in serverDefaults, and each server is defined in mcpServers 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.

{
  "serverDefaults": {
    // Optional shared defaults for all servers
  },
  "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

serverDefaults Section

Optional shared defaults inherited by all servers. Allowed keys:

• env
• timeout
• connectionTimeout
• requestTimeout
• oauth
• headers
• inheritParentEnv
• envFilter
• restartOnExit
• maxRestarts
• restartDelay

Merge behavior:

• env object values merge with per-server env values (server keys override serverDefaults keys).
• envFilter arrays merge with per-server entries appended after serverDefaults entries; duplicate patterns are kept only once.
• oauth and headers are replaced by per-server values (not merged).
• Primitive values (timeout, connectionTimeout, requestTimeout, inheritParentEnv, restartOnExit, maxRestarts, and restartDelay) are inherited only when missing on the server.
• Transport-specific exclusions apply: global headers are ignored for stdio transports, and global inheritParentEnv and envFilter are ignored for http, sse, and streamableHttp transports.
• Restart settings from serverDefaults apply only to stdio servers. They are ignored for http, sse, and streamableHttp transports.
• When both serverDefaults.env and mcpServers.<name>.env use array format, the server-specific array wins instead of merging element-by-element.

Migration Guide (Per-Server to Shared Defaults)

You can move repeated settings from each server into serverDefaults without changing server behavior:

1. Identify repeated keys across servers (env, connectionTimeout, requestTimeout, oauth, headers, inheritParentEnv, restartOnExit, maxRestarts, restartDelay).
2. Move shared values to serverDefaults.
3. Keep server-specific overrides inside each server definition.
4. Run 1mcp mcp status --verbose to confirm each server’s effective merged configuration.

serverDefaults Environment Variables Reference

serverDefaults.env supports two formats:

• Object format: { "KEY": "value" }
• Array format: ["KEY=value"]

When both serverDefaults.env and mcpServers.<name>.env are objects, values are merged and server values override serverDefaults values on key conflicts.

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, optional): Tags for routing and access control. Required for preset filtering to work correctly.
• connectionTimeout (number, optional): Connection timeout in milliseconds. Used when establishing initial connection. Takes precedence over timeout.
• requestTimeout (number, optional): Request timeout in milliseconds. Used for individual MCP operations (callTool, readResource, etc.). Takes precedence over timeout.
• timeout (number, optional): Deprecated fallback timeout in milliseconds. Used when specific timeouts are not set. New configurations should use connectionTimeout and requestTimeout.
• enabled (boolean, optional): Set to false to disable the server. Defaults to true.
• disabledTools (array of strings, optional): Hide selected tools from this server without disabling the entire server.

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.
• stderr (string or integer, optional): Controls the child process stderr target. Omitted, "pipe", or "overlapped" captures stderr in the 1MCP logger with bounded output (8 KiB per line, 20 unique lines per 10 seconds, and repeated-line summaries every 5 seconds). On Windows, "overlapped" uses overlapped I/O handles. Use "inherit" for direct terminal output, "ignore" to discard it, or a non-negative file descriptor to pass it through to the child process.
• restartOnExit (boolean, optional): Supervise the complete backend MCP connection and restart it when the child process exits. Applies only to stdio transports and defaults to false.
• maxRestarts (number, optional): Maximum consecutive automatic restart attempts. Omitted means 5, 0 means unlimited, and a positive value sets that limit. The counter resets after five stable minutes.
• restartDelay (number, optional): Initial automatic restart delay in milliseconds. Defaults to 1000 (1 second); consecutive failures wait 1x, 2x, 4x, 8x, then at most 16x this value.

Configuration Examples

Basic Configuration:

{
  "serverDefaults": {
    "connectionTimeout": 10000,
    "requestTimeout": 30000,
    "env": {
      "HTTP_PROXY": "${HTTP_PROXY}",
      "API_KEY": "${GLOBAL_API_KEY}"
    }
  },
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "/data"],
      "tags": ["files", "local-data"]
    },
    "remote-api": {
      "transport": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer local-token"
      },
      "tags": ["api", "prod"],
      "requestTimeout": 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"
      },
      "stderr": "pipe",
      "restartOnExit": true,
      "maxRestarts": 5,
      "restartDelay": 2000,
      "tags": ["production", "api"],
      "connectionTimeout": 10000,
      "requestTimeout": 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"]
    }
  }
}

Disabling Individual Tools

Use disabledTools when a server should stay enabled but selected tools should be hidden:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "disabledTools": ["write_file"]
    }
  }
}

Disabled tools are per-server only. Use logical server-local names such as write_file; runtime filtering also recognizes qualified names like filesystem_1mcp_write_file, but logical names are easier to maintain.

Manage this field with mcp tools:

npx -y @1mcp/agent mcp tools disable filesystem write_file
npx -y @1mcp/agent mcp tools enable filesystem write_file
npx -y @1mcp/agent mcp tools list filesystem --disabled

The mcp tools list, enable, and disable subcommands update mcp.json. A running 1mcp serve instance picks up the change through config hot reload.

If the same server name exists in both mcpTemplates and mcpServers, the template entry is authoritative. Tool enable/disable commands update mcpTemplates.<name>.disabledTools and leave any stale mcpServers.<name>.disabledTools value unchanged.

---

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", "HOME", "NODE_*", "NPM_*", "!SECRET_*", "!BASH_FUNC_*"]
}

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", "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 supervision for a stdio backend. Non-stdio transports ignore this setting.
• maxRestarts: Limit consecutive automatic restart attempts. Omit it for the default limit of 5, set it to 0 for unlimited attempts, or use a positive value for an explicit limit.
• restartDelay: Set the initial delay in milliseconds (default: 1000). Consecutive failures use bounded exponential backoff: 1x, 2x, 4x, 8x, and then 16x for every later attempt.

After the replacement MCP connection remains healthy for five minutes, its consecutive-attempt counter and backoff return to their initial values. Reaching a positive maxRestarts limit places that backend in crash-loop until an operator restarts it, configuration reload replaces it, or the runtime shuts down.

serverDefaults can provide these three settings for static servers and templates, but an explicit value on a server or template wins. Template supervision runs independently for each rendered instance. Recovery keeps that logical instance's identity, rendered configuration, and client memberships; removing or replacing the instance cancels pending recovery.

Automatic recovery creates a fresh process, transport, and MCP client connection. While recovery is in progress, the backend is unavailable and its capabilities and instructions are withdrawn; they are published again only after the replacement completes MCP initialization. In-flight requests fail normally and are not replayed.

For an immediate operator-initiated restart of a running backend, use mcp restart.

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",

      "inheritParentEnv": true,
      "envFilter": ["PATH", "HOME", "USER", "NODE_*", "NPM_*", "!SECRET_*", "!KEY_*", "!BASH_FUNC_*"],
      "env": {
        "NODE_ENV": "production",
        "API_KEY": "${PROD_API_KEY}",
        "DB_URL": "${DATABASE_CONNECTION}",
        "LOG_LEVEL": "info"
      },
      "restartOnExit": true,
      "maxRestarts": 3,
      "restartDelay": 1500,
      "tags": ["production", "api"],
      "connectionTimeout": 10000,
      "requestTimeout": 30000
    }
  }
}

---

Timeout Configuration

Timeout Hierarchy

1MCP Agent supports granular timeout configuration with the following precedence hierarchy:

• Connection Operations: connectionTimeout > timeout (fallback)
• Request Operations: requestTimeout > timeout (fallback)

Timeout Types

connectionTimeout

• Purpose: Timeout for establishing initial connection to MCP server
• Used when: Calling client.connect() during server startup or retry
• Units: Milliseconds
• Recommended: 5000-15000ms (5-15 seconds) depending on network conditions

requestTimeout

• Purpose: Timeout for individual MCP operations (tools, resources, etc.)
• Used when: callTool(), readResource(), listRoots(), etc.
• Units: Milliseconds
• Recommended: 15000-60000ms (15-60 seconds) depending on operation complexity

timeout (Deprecated)

• Purpose: Fallback timeout when specific timeouts are not set
• Status: Deprecated for new configurations
• Behavior: Used as fallback for both connection and request operations

Timeout Examples

Granular Timeout Configuration:

{
  "mcpServers": {
    "fast-api": {
      "transport": "http",
      "url": "https://fast-api.example.com/mcp",
      "connectionTimeout": 3000,
      "requestTimeout": 10000,
      "tags": ["api", "fast"]
    },
    "heavy-processor": {
      "transport": "http",
      "url": "https://heavy.example.com/mcp",
      "connectionTimeout": 10000,
      "requestTimeout": 120000,
      "tags": ["processing", "slow"]
    },
    "backward-compatible": {
      "transport": "http",
      "url": "https://legacy.example.com/mcp",
      "timeout": 30000,
      "tags": ["legacy"]
    }
  }
}

Transport-Specific Considerations:

• HTTP/SSE Transports: Require longer connection timeouts due to network latency
• STDIO Transports: Typically need shorter connection timeouts (local process)
• Retry Logic: Failed connections trigger transport recreation for HTTP/SSE

Migration from Single Timeout

Before (Deprecated):

{
  "timeout": 30000
}

After (Recommended):

{
  "connectionTimeout": 5000,
  "requestTimeout": 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.

---

MCP Server Templates

MCP Server Templates enable dynamic, context-aware server configuration. Instead of hardcoding server settings, you can define template configurations that automatically adapt based on runtime context like the current project, user, environment, or client connection.

Template Configuration

Templates are defined in the mcpTemplates section of your configuration:

{
  "mcpTemplates": {
    "project-filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "{{project.path}}"],
      "tags": ["filesystem", "project"]
    },
    "conditional-server": {
      "command": "node",
      "args": ["{{project.path}}/server.js"],
      "env": {
        "NODE_ENV": "{{project.environment}}",
        "DEBUG": "{{#if (eq project.environment 'development')}}true{{else}}false{{/if}}"
      },
      "disabled": "{{#if (eq project.environment 'production')}}true{{else}}false{{/if}}"
    }
  }
}

Available Template Variables

Templates have access to four namespaces of context variables:

Project Variables (project.*):

• project.path - Absolute path to current project
• project.name - Project directory name
• project.environment - Environment name
• project.git.branch - Git branch name
• project.custom.* - Custom values from .1mcprc file

User Variables (user.*):

• user.username - System username
• user.name - User's full name
• user.email - User email address
• user.home - Home directory path

Transport Variables (transport.*):

• transport.type - Transport protocol (http, sse, stdio)
• transport.client.name - Client application name (cursor, claude-code)
• transport.client.version - Client version

Template Syntax

1MCP uses Handlebars for template rendering:

{{project.path}}                           <!-- Variable access -->
{{#if (eq project.environment 'production')}}  <!-- Conditionals -->
  production-value
{{else}}
  development-value
{{/if}}
{{#if (and condition1 condition2)}}        <!-- Logical operators -->
{{/if}}

Context Enrichment (.1mcprc)

Project-level context can be enriched with a .1mcprc file:

{
  "preset": "my-team-preset",
  "tags": ["team-a", "backend"],
  "context": {
    "projectId": "myapp-backend",
    "environment": "development",
    "team": "platform",
    "custom": {
      "teamId": "team-a",
      "region": "us-west",
      "apiEndpoint": "https://dev-api.example.com"
    }
  }
}

Custom values are available as {{project.custom.*}} in templates.

Template Settings

Control template processing behavior:

{
  "templateSettings": {
    "validateOnReload": true,
    "failureMode": "graceful",
    "cacheContext": true
  }
}

Setting	Type	Description
validateOnReload	boolean	Validate templates when config is reloaded
failureMode	'strict'|'graceful'	How to handle template errors
cacheContext	boolean	Cache rendered templates by context hash

For complete documentation on templates, see the MCP Server Templates Guide and Template Syntax Reference.

---

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