Connect An Agent Via MCP

An MCP host reaches your Dotabases by launching the dots CLI in MCP mode. The steps below assume the CLI is installed and dots auth whoami already succeeds. Connect Your Agent covers the concepts behind the connection.

The Registration

Most hosts read an mcpServers map. Point one entry at the dots CLI in MCP mode:

{
  "mcpServers": {
    "dots": {
      "command": "dots",
      "args": ["mcp"]
    }
  }
}

Two hosts register the server from their own command line instead of taking a pasted block. Claude Code takes a user-scoped registration, which makes the server available in every project:

claude mcp add --scope user dots -- dots mcp

Codex writes the equivalent entry into its own config file:

codex mcp add dots -- dots mcp

Restart or reload the host after registering so it launches the server.

Where Each Host Keeps Its Config

Read-only Access

To connect a host that should read and search but never create, update, archive, or purge, add the --read-only flag to the launcher:

{
  "mcpServers": {
    "dots": {
      "command": "dots",
      "args": ["mcp", "--read-only"]
    }
  }
}

The flag drops the write catalog from the server: those tools are never registered, so the host cannot call them. The read-classed tools stay — including the Superpower tools and the batch meta-tool, which then refuses any write member at call time rather than pretending it can run one. Read-only is a property of the launched stdio server, so it holds even when the credential behind it is broader.

Deferred Tool Discovery

The catalog is large — 241 built-in tools — and a host that lists all of them spends context on capabilities the current task will never call. --defer-tools narrows the opening list to the 16 core tools plus discover_tools:

{
  "mcpServers": {
    "dots": {
      "command": "dots",
      "args": ["mcp", "--defer-tools"]
    }
  }
}

The remaining 225 built-in tools stay registered and granted — they are simply withheld from the initial list. When a task needs one, the agent calls discover_tools to activate a family, and the server signals the changed list so the host picks the new tools up.

It is an opt-in rather than a default because the server cannot detect whether a host refreshes its tool list: that is local configuration in the host's MCP client, not a capability MCP transmits. A host that never refreshes would be left unable to see an activated tool, so a launcher that does not pass the flag receives the complete granted catalog. Set it on a refreshing host — Claude Code is one — and leave it off elsewhere. dots mcp tools reports which class each tool falls in, so you can check whether a capability is missing or merely deferred before connecting a host at all.

Extending The Server

--plugin <dir> loads tool entry points from a plugin directory and registers them as runtime MCP tools alongside the built-in catalog. The flag is repeatable, and a runtime tool is gated exactly like a built-in: it registers only when the credential holds its required permission atom, and a write-classed one is skipped under --read-only.

Authentication

Running locally over stdio, the server reuses the credential the CLI already resolved — no token goes in the config. DOTS_API_KEY in the host's environment is the documented alternative when you would rather not write a credential to disk.

A remote host talks to the platform's Streamable HTTP endpoint at /api/v1/mcp instead. There, authenticate with a personal access token as a bearer credential and select the company with the x-dots-company header. An unauthenticated request is refused rather than downgraded.

Either way you can narrow what the agent sees by issuing a scoped credential rather than reusing your own. dots access credentials issue --scope <atom> mints one for a named principal, repeating --scope for each permission atom you want to grant; the Settings → MCP tab does the same from the app. The server registers only the tools whose atoms the credential holds, so a narrow token produces a narrow catalog.

Confirm It Works

Ask the agent to list your Dotabases or search for something you know exists. If it returns rows, the connection is live. claude mcp list and codex mcp list report registration state from the host side. See MCP Tools for everything the agent can now do.

If The Host Cannot Find It

The most common failure is that dots is not on the PATH the host process inherits — a host launched from the desktop does not always see a shell's PATH. Confirm the command resolves in a fresh terminal first, and if the host still cannot launch it, point the config at the CLI by absolute path instead of relying on lookup.