Skip to content

Connect an MCP server

DuckTapeKiller edited this page Sep 13, 2026 · 1 revision

The Model Context Protocol is a standard way for a program to offer tools to AI apps. An MCP server is such a program. Dive starts the servers you list, asks each one for its tools, and hands those tools to the model. The same server works in other MCP clients too, such as Claude Code.

MCP servers work in llama.cpp, LM Studio and Ollama mode. The MCP SERVERS section isn't shown in Cloud mode, and Pi mode has no MCP.

Before you start

You need whatever the server runs on. Dive only starts a server with one of these commands: npx, node, python, python3, uvx, deno or bun. Servers published for Node.js usually start with npx, and Python servers with uvx.

1. Open the MCP settings

Switch to the mode that should use the server, open Settings > TOOLS, and scroll to MCP SERVERS at the bottom.

2. Describe the server

Enter the servers as JSON. This example is the one Dive shows in the empty box:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "~/test.db"]
    }
  }
}
Part What it is
sqlite A name you choose. It becomes part of each tool's name
command The program to start: one of the commands above, or a full path to one of them
args The command's arguments, as a list of strings
env Optional environment variables for the server, as an object

3. Start it

Press SAVE & RESTART SERVERS. The status reads CONNECTING..., then how many servers connected and how many failed. Each server gets a badge:

  • the server's name and how many tools it offers, when it connected (point at the badge to see the tool names);
  • FAILED and the error, when it didn't.

4. Use it

Ask for something the server can do. Its tools reach the model under names of the form mcp__sqlite__<tool>, with the description and input schema the server provides. MCP tools don't ask for permission, and the model receives the text the tool returns.

Each mode has its own servers

A mode's server list is kept in the window's local storage and sent to Dive's server when you use that mode, so a server listed for llama.cpp doesn't start for Ollama. After Dive restarts, a mode's servers start again the first time you use the mode.

Saving a new list starts a fresh set of servers. A reply that is still running keeps using the old set until it finishes. Saving an empty list stops the mode's servers; saving invalid JSON leaves the running ones as they are.

The rules Dive enforces

A server that breaks one of these rules isn't started, and its badge shows why:

  • command must be npx, node, python, python3, uvx, deno or bun, either the bare name or a full path ending in one of them.
  • args must be a list of strings.
  • args can't contain -e, --eval, -c, --command, -p, --print, -i or --interactive, which would let a launcher run arbitrary code.

Dive adds /opt/homebrew/bin, /usr/local/bin, /usr/bin and /bin to the search path for these commands, because the macOS app starts with a minimal PATH that would otherwise miss Homebrew installs. Your env values are added on top of Dive's own environment.

Deleting downloads

DELETE DOWNLOADS asks first, then stops the mode's servers and deletes the folders named by absolute paths in each server's env, such as a package cache or a data folder. It only deletes folders at least two levels inside your home folder. The next save downloads everything again.

Troubleshooting

Message What to do
Command "..." is not on the allowlist (permitted: npx, node, python, python3, uvx, deno, bun). Start the server through one of those commands
args must be an array of strings. Write args as ["a", "b"]
args contains a forbidden execution flag. Remove the flag, and pass the server a script or package instead
server configuration must be an object. Each server needs { "command": ... }
INVALID JSON Check the JSON: quotes, commas and brackets
A badge says FAILED The error on the badge comes from starting the server. Check that the command runs in a terminal
Error: MCP server '...' is not active for ... The server isn't running in this mode. Press SAVE & RESTART SERVERS
Error executing MCP tool: ... The server reported an error for that call

For developers

  • mcp.js has initMcpServers() (checks the config and connects over stdio), getMcpOllamaTools() (turns MCP tools into function definitions) and executeMcpTool() (calls the tool and joins its text content). MCP_ALLOWED_COMMANDS is the allowlist.
  • Servers are grouped into one session per mode. A request takes a lease on its mode's session with acquireMcpSession() and releases it when it finishes, so reconfiguring a mode never pulls a server out from under a running tool call.
  • Endpoints: POST /api/mcp/config and POST /api/mcp/purge. The settings UI is saveMcpConfig() and purgeMcpDownloads() in assets/js/07-chat.js, and ensureMcpModeInitialised() sends a mode's saved list when the mode is used.
  • docs/mcp.md goes into sessions, leases and shutdown.

Read next

Clone this wiki locally