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, and a host that lists all of it spends context on capabilities the current task will never call. --defer-tools narrows the opening list to the core tools plus discover_tools:

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

Every deferred built-in stays 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. MCP Tools is generated from the live registry and carries the catalog's current size and its exact core and deferred split.

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

For local stdio, configure an agent login before starting the host:

dots auth login --setup-agent "Coding agent" --company <slug>

Setup creates or reuses a separate agent principal, explicitly assigns Editor, and stores a credential that expires after 90 days. The human login stays in place. The launcher selects the workspace's agent credential and verifies its identity before connecting; a missing or human credential is refused. No token goes in the host config. If the host sets DOTS_API_KEY, that override must also resolve to an agent. Remove a human override to use the stored agent login.

To use an existing agent with narrower grants, import its credential with dots auth login --agent --api-key-file <path> --company <slug>.

A remote host talks to the platform's Streamable HTTP endpoint at /api/v1/mcp instead. There, authenticate with an agent principal's 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. The Access agent creation flow grants the agent its permissions and issues its credential. The CLI also exposes dots access credentials issue --scope <atom> for a named principal, repeating --scope for each permission atom you want to allow. 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.