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 allows some special placeholder values in the env and headers fields on MCP Servers.

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": "uvx",
            "args": ["mcp-server-fetch"]
        }
    }
}

Required fields:

• command: The executable to start the server

Optional fields:

• args: Array of command arguments
• env: Optional environment variables

env Special Values

The env field supports several special values. 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	"SERVER_URL": "secret"	null falls back to process.env.API_KEY
"AUTH": "Bearer ${API_KEY}"	"AUTH": "Bearer secret"	${} Placeholder values are also replaced
"TOKEN": "$: cmd:op read op://example/token"	"TOKEN": "secret"	Values starting with $: will be executed as shell command
"HOME": "/home/ubuntu"	"HOME": "/home/ubuntu"	Used as-is

Remote Servers

MCPHub supports both streamable-http and sse remote servers.

{
    "mcpServers": {
        "remote-server": {
            "url": "https://api.example.com/mcp",
            "headers": {
                "Authorization": "Bearer ${API_KEY}"
            }
        }
    }
}

Required fields:

• url: Remote server endpoint

Optional fields:

• headers: Optional authentication headers

headers Special Values

The headers field supports ${...} Placeholder values. Given API_KEY=secret in the environment:

Example	Becomes	Description
"Authorization": "Bearer ${API_KEY}"	"AUTH": "Bearer secret"	${} Placeholder values are replaced

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}"],
            "custom_instructions": {
                "disabled": false,
                "text": "Custom instructions for this server"
            }
        }
    }
}