Quickstart: Agents

This page connects an MCP-capable assistant to your workspace, then narrows what it is allowed to do and gives it an identity of its own.

There are two situations, and they need different setups. An external agent runs in someone else's host — Claude Code, Claude Desktop, Cursor — and reaches your workspace over the Model Context Protocol. An internal agent is one you run yourself against your own data, and it should have a principal and a credential of its own rather than borrowing yours.

Both produce the same two outcomes: a connection that advertises only the tools its credential can satisfy, and an audit ledger that records which principal did what.

Connect An External Agent

The dots CLI is also an MCP server. A host launches it in MCP mode and attaches its tools to the model. Most hosts read an mcpServers map; point one entry at the CLI:

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

Over stdio the server reuses the credential the CLI already stored, so no token goes in the config file. Connect an Agent via MCP has the per-host registration details, including the one-line Claude Code form and where each host keeps that map.

The same server also answers over the network rather than stdio, which is how a hosted agent connects. There the credential travels as a bearer token and the company is chosen with a request header, because there is no local CLI whose stored credential the server could reuse.

You can check what the launcher offers before wiring a host to it:

dots mcp --help

Two flags are worth knowing. --read-only is the narrowing described below. --plugin takes a directory and repeats, and registers that plugin's tools alongside the built-in catalog.

What The Agent Gets

A connected agent sees 45 built-in tools. Each one declares the permission atom it requires, and the connection registers only the tools whose atom the connecting credential holds.

One tool sits outside that map. batch requires no atom and is always advertised, because it gates each of its own members individually instead. MCP Tools is the generated catalog — every tool, its parameters, and the atom it requires.

Scope Decides The Tool List

The tool list is not a fixed menu the host caches. When the server starts, it asks the platform what the connecting credential actually holds, and that answer is the union of the credential's workspace-effective permissions and every per-Dotabase grant it carries. A credential granted dotabase.read on a single Dotabase therefore advertises the read tools, and a credential granted nothing advertises almost nothing.

If that resolution fails — an offline daemon, a rejected credential, a network fault — the server fails closed rather than open. It advertises the ungated batch and nothing else, and writes the reason to standard error. A broken scope read never degrades into a full-authority connection.

The tool list is advertising rather than the enforcement boundary, and the routes behind the tools are what enforce access. The code-graph routes refuse a call the credential cannot make; the row reads instead scope every result to your company, so an over-advertised read returns your own data rather than an error. Narrowing the credential is what imposes a hard limit; a short tool list is not one.

Give It Only The Read Tools

If the host is untrusted, or the agent's job is answering questions rather than changing things, register it read-only:

dots mcp --read-only

That narrows the registered surface rather than hiding it in the interface. All 21 write tools go unregistered, so the model is handed no write tool it could call. What remains is the 19 read-classed tools plus batch — 20 in total. The Superpower tools stay registered, because listing and invoking a Superpower mutates nothing.

batch stays registered too, and screens every member it is handed. A write named inside a read-only batch is refused in place, with the reason attached to that member's slot rather than failing the whole call.

Batch Several Calls In One Round Trip

batch takes a list of operations and runs them under one tool call, which matters when an agent is assembling context and would otherwise burn a turn per read.

Reads in the list fan out concurrently. Writes run in the order you listed them, and if one fails the remaining writes are halted rather than half-applied; the response names the index that failed, and reads that already completed still stand. Results come back aligned to the input list, so the third result belongs to the third operation whatever happened to the others.

Each batched write is recorded in the audit ledger under its own tool name, never under batch, so bundling calls for efficiency does not blur what the agent did.

Give An Internal Agent Its Own Identity

An agent is a principal, like a person. Sharing your own credential with it gives it everything you can do and makes its actions indistinguishable from yours in the ledger. Create it with zero authority instead, then grant it exactly the Dotabases it needs. The examples below use one with the slug reading-list:

dots access agents create "Research assistant" --grant reading-list:editor

A grant is <dotabase>:<preset> or <dotabase>:<comma-separated atoms>, and the flag repeats. If a preset is wider than the job, name the atoms directly. The full vocabulary — every atom, which are Dotabase-scoped, and what each system role carries — prints from the catalog:

dots access catalog

Issue the principal a credential of its own, optionally narrowed further to specific atoms. The raw token is shown once, at issue, and is not retrievable afterwards:

dots access credentials issue --principal "Research assistant" --name "mcp-session" --scope dotabase.read

Scopes narrow and never widen. Naming an atom the principal was never granted does not confer it — the effective authority of a request is the overlap between what the principal holds and what the token allows. Issue Scoped Agent Credentials walks the whole chain, including expiry, revocation by credential id, and the runtime profile that decides which tools a chat turn even offers the agent.

Everything that principal does lands in the audit ledger under its own name:

dots access audit --limit 20

Confirm The Connection

Ask the connected agent to list your Dotabases or search for something you know exists. From your side, the same reads look like this:

dots auth whoami
dots search "onboarding" --limit 5
dots rows get reading-list READ-1

Those two reads are the halves of one pattern. The search is a survey, so it answers at the summary disclosure level — identity and classification per hit, with a footer naming the tier — which is enough for either of you to choose. The rows get beneath it names a single record, so it defaults to the widest tier and hands the row back whole. Survey cheaply, then select: --level full widens a survey read to that same width when you want it, and --fields steps outside the ladder for an exact allowlist.

A row comes back as an agent envelope — YAML frontmatter over a Markdown body. The frontmatter leads with identity, so human_id and title are the first things either of you reads, and stored option ids are resolved to the labels you chose rather than being handed over raw.

The site, the CLI and the MCP tools render that envelope through one shared renderer, so what you see and what the model sees do not drift. Only the transport chrome differs: the CLI may append a compact context trailer in agent mode, while the MCP tools deliver the same information on a structured channel beside the text.

Where To Go Next

MCP Tools is the full catalog, with the permission atom each tool requires. Agent Envelope explains the record block every surface shares. Issue Scoped Agent Credentials is the long form of the identity section above. To scope a whole team rather than one agent, see Quickstart: Teams.