MCP Config File
MCPHub.nvim like other MCP clients uses a JSON configuration file to manage MCP servers. This config
file is located at ~/.config/mcphub/servers.json
by default and supports real-time updates across all Neovim instances. You can set config
option to a custom location.
NOTE
You can use a single config file for any MCP client like VSCode, Cursor, Cline, Zed etc as long as the config file follows the below structure. With MCPHub.nvim, config
file can be safely added to source control as it supports universal ${}
placeholder syntax for environment variables and command execution across all configuration fields.
Manage Servers
Adding, editing, deleting and securing MCP servers in easy and intuitive with MCP Hub. You don't need to edit the servers.json
file directly. Everything can be done right from the UI.
From Marketplace
Browse, sort, filter , search from available MCP servers.
One click AI install with Avante and CodeCompanion
Or Simple copy paste mcpServers
json block in the README
From Hub View
Add (<A>
), edit (<e>
), delete (<d>
) MCP servers from the (H
) Hub view.
Basic Schema
The config
file should have a mcpServers
key. This contains stdio
and remote
MCP servers. There is also another top level MCPHub specific field nativeMCPServers
to store any disabled tools, custom instructions etc that the plugin updates internally. See Lua MCP Servers for more about Lua native MCP servers
{
"mcpServers": {
// Add stdio and remote MCP servers here
},
"nativeMCPServers": { // MCPHub specific
// To store disabled tools, custom instructions etc
}
}
Server Types
Local (stdio) Servers
{
"mcpServers": {
"local-server": {
"command": "${MCP_BINARY_PATH}/server",
"args": [
"--token", "${API_TOKEN}",
"--secret", "${cmd: op read op://vault/secret}"
],
"env": {
"API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
"DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
"DB_PASSWORD": "password123",
"FALLBACK_VAR": null
}
}
}
}
Required fields:
command
: The executable to start the server (supports${VARIABLE}
and${cmd: command}
)
Optional fields:
args
: Array of command arguments (supports${VARIABLE}
and${cmd: command}
placeholders)env
: Environment variables with placeholder resolution and system fallbackdev
: Development mode configuration for auto-restart on file changesname
: Display name that will be shown in the UIdescription
: Short description about the server (useful when the server is disabled andauto_toggle_mcp_servers
istrue
)
Universal ${}
Placeholder Syntax
All fields support the universal placeholder syntax:
${ENV_VAR}
- Resolves environment variables${cmd: command args}
- Executes commands and uses outputnull
or""
- Falls back toprocess.env
Given API_KEY=secret
in the environment:
Example | Becomes | Description |
---|---|---|
"API_KEY": "" | "API_KEY": "secret" | Empty string falls back to process.env.API_KEY |
"API_KEY": null | "API_KEY": "secret" | null falls back to process.env.API_KEY |
"AUTH": "Bearer ${API_KEY}" | "AUTH": "Bearer secret" | ${} Placeholder values are replaced |
"TOKEN": "${cmd: op read op://vault/token}" | "TOKEN": "secret" | Commands are executed and output used |
"HOME": "/home/ubuntu" | "HOME": "/home/ubuntu" | Used as-is |
⚠️ Legacy Syntax:
$VAR
(args) and$: command
(env) are deprecated but still supported with warnings. Use${VAR}
and${cmd: command}
instead.
dev
Development Mode
The dev
field enables automatic server restarts when files change during development:
{
"mcpServers": {
"dev-server": {
"command": "npx",
"args": [
"tsx",
"path/to/src/index.ts"
],
"dev": {
"watch": [
"src/**/*.ts",
"package.json"
],
"enabled": true,
"cwd": "/path/to/dev-server/"
}
}
}
}
Dev Configuration Options:
Field | Required | Default | Description |
---|---|---|---|
cwd | Yes | - | Absolute path to server's working directory |
watch | No | ["**/*.js", "**/*.ts", "**/*.py","**/*.json"] | Array of glob patterns to watch |
enabled | No | true | Enable/disable dev mode |
When enabled, the server will automatically restart whenever files matching the watch patterns change in the specified directory. The system uses a 500ms debounce to prevent rapid restarts and ignores common directories like node_modules
, build
, .git
, etc.
Example use cases:
- TypeScript/JavaScript MCP servers during development. Use
npx tsc index.ts
to bypass build step during development. - Python servers with source code changes
- Configuration file updates that require restarts
Remote Servers
MCPHub supports both streamable-http
and sse
remote servers.
{
"mcpServers": {
"remote-server": {
"url": "https://${PRIVATE_DOMAIN}/mcp",
"headers": {
"Authorization": "Bearer ${cmd: op read op://vault/api/token}",
"X-Custom-Header": "${CUSTOM_VALUE}"
}
}
}
}
Required fields:
url
: Remote server endpoint (supports${VARIABLE}
and${cmd: command}
placeholders)
Optional fields:
headers
: Authentication headers (supports${VARIABLE}
and${cmd: command}
placeholders)name
: Display name that will be shown in the UIdescription
: Short description about the server (useful when the server is disabled andauto_toggle_mcp_servers
istrue
)
Note: Remote servers use the same universal
${}
placeholder syntax as local servers. See the Universal Placeholder Syntax section above for full details.
MCPHub Specific Fields
MCPHub adds several extra keys for each server automatically from the UI:
{
"mcpServers": {
"example": {
"disabled": false,
"disabled_tools": ["expensive-tool"],
"disabled_resources": ["resource://large-data"],
"disabled_resourceTemplates": ["resource://{type}/{id}"],
"autoApprove": ["safe-tool", "read-only-tool"],
"custom_instructions": {
"disabled": false,
"text": "Custom instructions for this server"
}
}
}
}
Auto-Approval Configuration
The autoApprove
field allows fine-grained control over which tools are automatically approved without user confirmation:
Value | Behavior | Example |
---|---|---|
true | Auto-approve all tools on this server | "autoApprove": true |
["tool1", "tool2"] | Auto-approve only specific tools | "autoApprove": ["read_file", "list_files"] |
[] or omitted | No auto-approval (show confirmation dialog) | "autoApprove": [] |
Notes:
- Resources are always auto-approved by default (no explicit configuration needed)
- Auto-approval only applies to enabled servers and enabled tools
- You can toggle auto-approval from the UI using the
a
keymap on servers or individual tools