Configuration Reference

RouterMCP uses a JSONC (JSON with Comments) configuration file named routermcp.jsonc in your project root.

Root Configuration

{
  "httpServer": {
    "port": 5151,
    "host": "127.0.0.1"
  },

  "session": {
    "timeout": 300,
    "max_sessions": 25
  },

  "codeMode": {
    "enabled": true,
    "timeout": 30000,
    "allowFetch": true
  },

  "mcpServers": {
    "server-name": {
      // Server configuration
    }
  }
}

HTTP Server Options

Option	Default	Description
`port`	`5151`	Port for HTTP server
`host`	`127.0.0.1`	Host to bind to

Session Options

Option	Default	Description
`timeout`	`300`	Session timeout in seconds
`max_sessions`	`25`	Maximum concurrent sessions

Code Mode Options

Option	Default	Description
`enabled`	`false`	Enable Code Mode
`timeout`	`30000`	Execution timeout in ms
`allowFetch`	`true`	Allow fetch() in sandbox

Server Configuration

Each server in mcpServers supports the following options.

Transport Configuration

Transport type is auto-detected from config keys:

command key → stdio transport
url key → HTTP streamable transport

You can also explicitly set "transport": "stdio" or "transport": "http-streamable".

Stdio Transport

For local processes:

{
  "command": "npx",
  "args": ["-y", "package-name"],
  "env": {
    "KEY": "value",
    "ANOTHER_KEY": "${env:ENV_VAR}"
  },
  "cwd": "/working/directory"
}

Option	Description
`command`	Command to execute
`args`	Arguments array
`env`	Environment variables
`cwd`	Working directory

HTTP Transport

For remote servers:

{
  "url": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer ${env:TOKEN}",
    "X-Custom-Header": "value"
  }
}

Option	Description
`url`	MCP server URL
`headers`	HTTP headers

Server Control

{
  "enabled": true
}

Set enabled: false to disable a server without removing its configuration.

Environment Variable Substitution

Use ${env:VAR_NAME} syntax anywhere in configuration values:

{
  "strictEnvVars": true,  // Fail if any ${env:...} cannot be resolved (default: false)
  "mcpServers": {
    "api": {
      "url": "${env:API_URL}",
      "headers": {
        "Authorization": "Bearer ${env:API_TOKEN}",
        "X-Env": "${env:ENVIRONMENT:-production}"
      }
    },
    "local": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "${env:SECRET_API_KEY}",
        "PORT": "${env:PORT:-3000}"
      }
    }
  }
}

Syntax Reference

Syntax	Description	If Variable Missing
`${env:VAR}`	Environment variable	Leaves unexpanded (error if `strictEnvVars: true`)
`${env:VAR:-default}`	With default value	Uses default value
`${VAR}`	Legacy syntax (deprecated)	Replaces with empty string

Examples:

${env:API_KEY} → Value of API_KEY or leaves as ${env:API_KEY} if missing
${env:PORT:-8080} → Value of PORT or 8080 if missing
${env:OPTIONAL:-} → Value of OPTIONAL or empty string if missing

Environment variables are resolved at runtime from your shell environment. Use strictEnvVars: true to catch missing variables early.

Complete Examples

Basic Filesystem Server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
      "allowedToolsGlob": ["read_*", "list_*", "search_*"],
      "denyTools": ["write_file", "delete_file"]
    }
  }
}

Remote HTTP Server with Authentication

{
  "mcpServers": {
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:API_TOKEN}",
        "X-API-Version": "v1"
      },
      "denyToolsGlob": ["admin_*", "*_delete"]
    }
  }
}

Multiple Servers

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/safe/path"],
      "allowedToolsGlob": ["read_*", "list_*"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-git"],
      "denyToolsGlob": ["*_force", "*_reset"]
    },
    "database": {
      "url": "${env:DB_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${env:DB_TOKEN}"
      },
      "allowedTools": ["query", "read_table"]
    }
  }
}

With HTTP Server and Code Mode

{
  "httpServer": {
    "port": 8080,
    "host": "0.0.0.0"
  },
  "codeMode": {
    "enabled": true,
    "timeout": 30000
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Configuration Reference

On this page