Neovim MCP Setup: Integrating Model Context Protocol in Neovim

Configuring Neovim as an AI-assisted development environment hits an immediate barrier when models need context beyond the current buffer or local Git tree. Pointing editor plugins at local filesystem folders or trying to run local embedding models inside the editor process degrades terminal responsiveness, swamps system memory, and stalls buffer navigation. The practical architecture is to separate the editor interface from knowledge storage, using Neovim as an active client to an external protocol layer.

Neovim MCP is the integration of the Model Context Protocol within Neovim via client plugins such as mcphub.nvim, allowing AI assistants inside the editor to query external data sources and tools. Model Context Protocol is an open standard for connecting AI models to external tools and services. Rather than requiring developers to install separate command-line wrappers for every data source, MCP establishes a standard JSON-RPC interface for tool discovery, resource retrieval, and prompt execution.

Existing writeups treat Neovim solely as an MCP server for external agents to control, ignoring the high-demand workflow where Neovim acts as a client querying external knowledge. In that server-only pattern, an external orchestrator running in Claude Desktop or an autonomous daemon drives Neovim over an RPC socket to inspect open windows and manipulate buffers. While that pattern assists external agents, developers spending their working hours inside the terminal need the reverse relationship. They need Neovim to function as an MCP client where in-editor AI assistants query documentation repositories, issue trackers, database schemas, and shared workspaces directly from the command buffer.

A Neovim MCP client architecture consists of three distinct layers:

1. The Editor UI Layer: Neovim frontends such as CodeCompanion.nvim and Avante.nvim handle chat windows, inline code completion, prompt generation, and buffer diffing.

2. The MCP Hub Process: A coordination plugin, primarily mcphub.nvim, acts as an in-editor bridge. It boots a lightweight node process that manages server lifecycles, parses server configuration files, negotiates transport protocols, and aggregates tool definitions into a single Neovim API surface.

3. The Server Layer: External processes that expose tools, resources, and prompt templates. These split into two operational modes:

• Local stdio servers: Executables running locally on the developer workstation, communicating through standard input and output streams. These are suitable for localized tasks such as running Git commands, querying a local SQLite database, or inspecting workstation files.
• Remote HTTP servers: Remote services accessed over Streamable HTTP. These connect Neovim to centralized infrastructure, team documentation hubs, and cloud workspaces without placing indexing loads on the local machine.

Choosing between local stdio and remote HTTP transports determines how much workstation memory your Neovim instance consumes. Local servers run as child processes under Neovim. If you attach five separate stdio servers for different project repositories, your operating system spawns five Node.js or Python runtime instances. If those servers attempt to maintain local vector embeddings, memory consumption climbs quickly and causes input latency in terminal buffers.

Remote MCP connections keep memory consumption low by avoiding local embedding processes in the editor runtime. When Neovim communicates with an external storage workspace over Streamable HTTP, semantic search, document chunking, and metadata filtering execute on remote cloud infrastructure. Neovim receives only the exact text fragments required for the immediate code completion or prompt task. Developers looking to implement persistent storage for autonomous processes can review Fastio storage for agents and examine how Fastio workspaces organize team context.

• Roo Code MCP Setup: Connecting Coding Agents to Cloud WorkspacesRoo Code MCP connects the Roo Code autonomous coding extension in VS Code to local tools and remote Model Context...
• Best MCP Clients for 2026: Connect Your AI to Any ToolMCP clients are AI interfaces like Claude Desktop, Cursor, or specialized IDEs that implement the Model Context...
• MCP Server Examples: Practical Implementations for AI AgentsThe Model Context Protocol ecosystem has grown past 1,000 public servers, but finding the right implementation for your...
• How to Build a Model Context Protocol (MCP) ServerExposing databases, local filesystems, or custom APIs to AI agents usually requires custom integration code and manual...
• MCP Server Architecture: How Model Context Protocol Servers WorkThe Model Context Protocol defines a three-layer architecture where hosts, clients, and servers communicate over...
• Box MCP Server Setup and AI Agent Storage IntegrationA Box MCP server allows AI agents to interact with Box enterprise files and folders using the standardized Model...

More on this subject: MCP and Model Context Protocol (232 guides)

Setting up Neovim as an MCP client requires a plugin manager such as lazy.nvim, a modern Neovim installation (version 0.8.0 or newer), and Node.js (version 18.0.0 or newer). The plugin mcphub.nvim provides a unified hub for managing both stdio and remote HTTP MCP servers inside Neovim.

To install mcphub.nvim using lazy.nvim, create or update a plugin configuration file in your Neovim configuration directory, such as lua/plugins/mcphub.lua.

return {
  "ravitemer/mcphub.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
  },
  build = "bundled_build.lua",
  config = function()
    require("mcphub").setup({
      port = 3000,
      config = vim.fn.expand("~/.config/mcphub/servers.json"),
      on_ready = function(hub)
        vim.notify("MCP Hub initialized successfully", vim.log.levels.INFO)
      end,
    })
  end,
}

The configuration sets three core parameters:

• port: Specifies the local port on which the internal hub daemon listens for client connections. The default is 3000.
• config: Defines the path to your server registry file. Storing this configuration in ~/.config/mcphub/servers.json keeps your MCP server definitions centralized across multiple Neovim projects.
• on_ready: An optional callback that triggers when the hub process completes its initial handshake and loads active tool definitions.

The servers.json file uses the standard Model Context Protocol schema. It defines each server under a top-level mcpServers object. The hub supports both local processes and remote Streamable HTTP endpoints side by side:

{
  "mcpServers": {
    "filesystem-local": {
      "command": "node",
      "args": ["/usr/local/lib/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "/home/developer/projects"]
    },
    "team-workspace": {
      "url": "https://mcp.fast.io/mcp/code",
      "headers": {
        "Authorization": "Bearer ${FASTIO_API_KEY}"
      }
    }
  }
}

In this registry configuration:

• The filesystem-local entry executes a local Node.js binary over standard I/O. It accepts arguments defining which local directory tree the server may read.
• The team-workspace entry establishes a remote connection over Streamable HTTP to https://mcp.fast.io/mcp/code. Authentication is passed directly in the HTTP request headers using an environment variable reference. mcphub.nvim resolves ${FASTIO_API_KEY} from your active shell environment when initializing the connection.

Once installed, restart Neovim and run :checkhealth mcphub to verify that your environment meets runtime requirements. You can open the interactive hub management interface at any time by executing:

:MCPHub

The :MCPHub dashboard opens a floating buffer listing all configured servers, their connection status, available tools, exposed prompts, and resource URIs. From this interface, you can restart individual servers, inspect tool call arguments, test tool execution with custom JSON payloads, and monitor communication errors in real time.

With mcphub.nvim managing server lifecycles, you can bridge your MCP tools directly into Neovim AI plugins. The two primary AI completion and chat plugins in the modern Neovim ecosystem are CodeCompanion.nvim and Avante.nvim. Both support tool calling through mcphub.nvim.

CodeCompanion.nvim includes built-in extension support for mcphub.nvim. To connect them, declare mcphub inside your CodeCompanion setup configuration:

return {
  "olimorris/codecompanion.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "nvim-treesitter/nvim-treesitter",
    "ravitemer/mcphub.nvim",
  },
  config = function()
    require("codecompanion").setup({
      strategies = {
        chat = {
          adapter = "anthropic",
        },
        inline = {
          adapter = "anthropic",
        },
      },
      extensions = {
        mcphub = {
          callback = "mcphub.extensions.codecompanion",
          opts = {
            make_vars = true,
            make_slash_commands = true,
            show_result_in_chat = true,
            requires_approval = true,
          },
        },
      },
    })
  end,
}

This configuration exposes three interaction patterns within CodeCompanion chat buffers:

1. Explicit Tool Invocation: Type @mcp in the chat buffer to view all active tools provided by your configured MCP servers. You can select specific tools, such as repository search or database queries, to bind them to your prompt.

2. Variable Expansion: When make_vars = true is enabled, MCP resources appear as #variables in the chat window. If a connected server exposes an architectural blueprint or an API specification, typing #team-workspace:specs/auth.md injects the contents of that remote resource directly into the prompt context without copying files into the local buffer.

3. Slash Commands: When make_slash_commands = true is enabled, predefined prompt templates from your MCP servers map directly to /commands inside the chat window.

Setting requires_approval = true is a critical safety control. When an AI model decides to call an MCP tool, CodeCompanion pauses execution and renders a confirmation prompt displaying the tool name and argument payload. You can inspect the target path or query parameter before permitting the tool to execute.

For developers using Avante.nvim, mcphub.nvim integrates through dynamic system prompt configuration. In your Avante setup file, extract active server definitions from the hub instance to inform the model of available capabilities:

return {
  "yetone/avante.nvim",
  dependencies = {
    "nvim-treesitter/nvim-treesitter",
    "stevearc/dressing.nvim",
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
    "ravitemer/mcphub.nvim",
  },
  opts = {
    provider = "claude",
    system_prompt = function()
      local hub = require("mcphub").get_hub_instance()
      if hub then
        return hub:get_active_servers_prompt()
      end
      return ""
    end,
  },
}

This dynamic hook reads the active tool registry from mcphub.nvim whenever Avante initializes a generation task. The model receives a structured list of available tools, input parameters, and usage descriptions, enabling autonomous tool calling during inline edits and sidebar discussions.

Connect Neovim to Your Team's Cloud Workspace

Give CodeCompanion and Avante instant access to indexed project documentation, specs, and cloud files over Streamable HTTP without terminal lag. Monthly plans start with a 14-day free trial, which requires a credit card.

Start 14-Day Trial

Software development teams rarely store all documentation, API definitions, and architectural decisions inside the application repository. Non-code requirements, compliance checklists, design assets, and client specifications frequently live across enterprise cloud storage providers such as Google Drive, Microsoft OneDrive, Dropbox, Box, or SharePoint document libraries.

Developers attempting to give Neovim AI tools access to these documents face immediate operational hurdles with native connectors and local desktop sync clients:

• Virtual File Stubs and Desktop Sync Locks: Desktop clients for OneDrive (Files-On-Demand) and Google Drive (Drive for Desktop) use virtual file placeholders to save disk space. When a local stdio filesystem server attempts to read a virtual file path, the operating system attempts on-demand hydration. If network connectivity drops or the sync daemon stalls, the stdio process locks. This freezes Neovim's terminal input thread until the system call times out.
• Unstructured Retrieval and Context Flooding: Native cloud storage APIs return whole file payloads. When an AI plugin asks a question about an API payload format, pulling an entire requirements document or lengthy compliance manual exhausts the model context window, raises inference costs, and dilutes retrieval precision.

The reliable architectural path keeps files in your existing storage provider while delegating indexing and retrieval to an intelligent workspace:

1. Maintain Existing Cloud Storage: Your engineering team continues storing documents in Dropbox, Box, or OneDrive.

2. Scheduled Cloud Sync: Connect your storage provider to a Fastio workspace using Cloud Sync. Sync runs one-way or two-way, on a schedule or on demand, never continuous or real-time. SharePoint document libraries connect directly through the OneDrive connector.

3. Intelligence Mode and Semantic Indexing: Once files enter the workspace, Intelligence Mode auto-indexes text, PDFs, presentations, and technical documentation. It creates a hybrid search index combining full-text search with semantic retrieval. When the workspace needs to extract structured records from unstructured documents, Metadata Views turn files into queryable schemas without manual parsing rules, accessible at Fastio document data extraction.

4. Remote MCP Access: Neovim connects directly to the workspace over Streamable HTTP at https://mcp.fast.io/mcp/code. Setup steps for people are documented at https://mcp.fast.io/docs, while agents can inspect tool parameters at https://mcp.fast.io/skill.md.

When CodeCompanion or Avante issues a query, the model executes a search tool against the indexed workspace. The remote endpoint returns only the relevant excerpts and paragraphs with source citations. The editor runtime performs zero document parsing and downloads zero virtual file stubs.

Performance benchmarks confirm the efficiency of this remote workspace connector model. The connector comparison is published at https://fast.io/benchmarks/ and that page is the only place its numbers live. Fastio was measured the fastest and the lowest cost of the providers tested.

To connect your Neovim configuration to a Fastio workspace, generate a scoped API key in your account settings. In your terminal shell profile (such as ~/.zshrc), export your credential:

export FASTIO_API_KEY="your-fastio-api-token"

Then add the endpoint to ~/.config/mcphub/servers.json:

{
  "mcpServers": {
    "fastio-code": {
      "url": "https://mcp.fast.io/mcp/code",
      "headers": {
        "Authorization": "Bearer ${FASTIO_API_KEY}"
      }
    }
  }
}

Monthly plans start with a 14-day free trial that requires a credit card. Paid subscriptions provide team seats, storage, and credits for workspace intelligence:

Credits meter AI work. Storage and seats come with the plan. Review full plan details on the Fastio pricing page.

Running Model Context Protocol servers inside a text editor requires careful resource governance. Unlike monolithic IDEs that allocate gigabytes of memory to background language servers, Neovim users choose the editor specifically for its speed, minimal memory footprint, and low input latency. Maintaining that performance profile requires strict process hygiene when configuring MCP servers.

Local stdio servers execute as child processes of Neovim or its hub daemon. If a local server leaks memory, crashes, or triggers runaway CPU loops during file indexing, Neovim's terminal rendering can stutter. You can isolate and diagnose process performance with three practices:

1. Offload Heavy Indexing to Remote Servers: Keep local stdio servers focused on fast, synchronous operations like Git status or local AST parsing. Offload semantic search, document ingestion, vector calculations, and PDF parsing to remote HTTP servers. Because remote servers run on cloud infrastructure, large file processing has zero impact on your workstation CPU or terminal frame rate.

2. Manage Credentials Outside Repository Boundaries: Never commit hardcoded API keys into project-level configuration files such as .mcpservers.json or Neovim Lua files. Always use shell environment variables resolved dynamically at runtime by mcphub.nvim (${FASTIO_API_KEY}), or pull tokens from password managers using command interpolation syntax ($: cmd:op read op://developer/fastio/token).

3. Advisory File Locking for Concurrent Access: When multiple developers or autonomous coding agents collaborate within the same storage workspace, concurrent file writes can overwrite edits. Fastio provides advisory per-file leases managed directly through MCP actions. Clients acquire a lease using lock-acquire on storage_manage, check lease ownership using lock-status on storage, and release it with lock-release on storage_manage. The lock is advisory, meaning it never prevents writes or corrupts local buffers. If two writers submit changes simultaneously, both versions land safely, and per-file version history preserves every revision for audit and recovery.

4. Connection Diagnostics and Health Monitoring: If an MCP server fails to respond during editor startup, check your network connectivity and daemon logs. You can inspect the mcphub.nvim log file by running:

:lua vim.cmd("edit " .. vim.fn.stdpath("state") .. "/mcphub.log")

For remote Streamable HTTP connections, ensure your corporate firewall allows outbound HTTPS traffic to your server endpoint. The server echoes a session identifier in the Mcp-Session-Id header and expects the client to pass MCP-Protocol-Version on subsequent requests. When connections drop or become stale after machine sleep cycles, run :MCPHub and press <leader>r on the affected server to restart the transport channel without restarting your Neovim session.