Connecting MCP Servers

Dominir supports the Model Context Protocol (MCP), which lets you connect external tool servers to the platform. Once connected, an MCP server's tools are available to any agent you configure — indistinguishable from built-in capabilities like reading the graph or executing code.

What this enables

The built-in tool set covers Dominir's own data layer: reading and writing records, graph traversal, code execution, and artifact management. MCP servers extend this with whatever capabilities the server exposes: reading files from disk, querying external databases, calling APIs, controlling browsers, or any other tool that has been packaged as an MCP server.

The agent that uses these tools does not treat them differently. It receives a list of available tools, calls them, and gets results back — whether those results come from Dominir's Kernel or from an external process makes no difference to the agent's reasoning.

Connecting a server

Open Settings → MCP Servers in the interface. Click Add Server and fill in four fields:

Name — A label you choose. This becomes the prefix for all tools from this server. Use something short and without spaces (e.g. filesystem, github, slack). Hyphens are allowed; they are converted to underscores in the tool names.

Command — The executable to run. For Node.js servers distributed via npm, this is typically npx. For Python servers, it might be python or uvx. The command must be available on your system.

Arguments — The arguments passed to the command, space-separated. For an npm server: -y @modelcontextprotocol/server-filesystem /path/to/allow. Check the server's documentation for the correct arguments.

Environment — Optional environment variables the server needs, one per line in KEY=value format. Use this for API keys and tokens the server requires. These variables are passed only to the server process — they do not affect the rest of the system.

Click Connect. The Kernel spawns the server as a subprocess and negotiates the tool list. Once the status indicator turns green, the server's tools are registered and ready.

Tool names

Each tool from a connected server is prefixed with the server's name. A server named filesystem with a tool called read_file becomes mcp_filesystem__read_file in the tool list. A server named my-server uses mcp_my_server__ as the prefix (hyphens become underscores).

When configuring an agent's allowed tools, you can grant access to:

• ▸A specific tool: mcp_filesystem__read_file
• ▸All tools from a server: mcp_filesystem (matches everything from that server)

Connection status

The server panel shows four possible states:

A server in the Error or Offline state shows a reconnect button. Click it to attempt a fresh connection without reconfiguring.

Persistence and startup

Server configurations are saved to disk. When the Kernel restarts, all enabled servers are reconnected automatically. Each server connects independently — a failure to start one server does not prevent others from connecting.

To temporarily disable a server without removing its configuration, use the toggle in the server's detail panel. Disabled servers are not started at Kernel launch but remain in the list for when you need them.

Important: Node.js servers

Many MCP servers are distributed as npm packages and launched with npx. When Dominir runs as a background service (rather than from a terminal), the system PATH may not include your Node.js installation. The Kernel compensates for this automatically by checking the most common Node.js install locations (Homebrew, nvm, Volta) before spawning the server process.

If a Node.js server fails to connect with a "command not found" error, verify that node and npx are accessible from a terminal on the same machine. If they are installed in an unusual location, you can supply the full absolute path to npx in the Command field.

Budget behavior for search and fetch tools

When a connected server provides web search or URL fetch tools, the Kernel automatically adds guidance to those tools' descriptions encouraging agents to use them economically — one call per round, read the results before issuing another. This is applied at connection time and is invisible to the agent configuration. You do not need to configure anything for this behavior; it is on by default.

Removing a server

Select the server in the panel and click the remove button. The server's subprocess is terminated immediately and all of its tools are removed from the registry. Any agent runs that were actively using a tool from that server will receive an error on the next call to that tool.

JSON reference

For integrations that configure MCP servers programmatically rather than through the UI.

Adding a server

POST /apps/assistant/mcp/servers

{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"],
  "env": {}
}

• ▸name — required. Must be unique. Becomes the tool prefix.
• ▸command — required. The executable to spawn.
• ▸args — optional. List of arguments passed to the command.
• ▸env — optional. Key-value pairs merged into the server's environment.

Returns the server status object immediately after the connection attempt:

{
  "name": "filesystem",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"],
  "status": "connected",
  "tools": [
    "mcp_filesystem__read_file",
    "mcp_filesystem__write_file",
    "mcp_filesystem__list_directory"
  ],
  "error": null
}

If the connection fails, status is "error" and error contains the failure message.

Listing servers

GET /apps/assistant/mcp/servers

{
  "servers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"],
      "status": "connected",
      "tools": [
        "mcp_filesystem__read_file",
        "mcp_filesystem__write_file",
        "mcp_filesystem__list_directory"
      ],
      "error": null
    }
  ]
}

Reconnecting

POST /apps/assistant/mcp/servers/{name}/reconnect

No request body. Returns the same server status object as the add endpoint.

Removing

DELETE /apps/assistant/mcp/servers/{name}

{ "ok": true }

Server with environment variables

{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
  }
}

Environment variables supplied here are passed only to the MCP server subprocess. They are not visible to agents, not logged, and not stored in the graph — only in the server configuration file on disk.