# Agents

`knotless-mcp` is an MCP server. An agent connected to it reads and changes
repositories as your account, with no clone and no checkout. The [MCP tools
reference](../reference/mcp.md) lists what it can do.

## Connect a local client

`knotless-mcp` comes with the [install](getting-started.md#install). Log in
as the account the agent should act as, then add the server to your client:

```sh
knotless login you.bsky.social
claude mcp add knotless -- knotless-mcp   # Claude Code
```

Other clients, such as Claude Desktop (`claude_desktop_config.json`) and
Cursor (`.cursor/mcp.json`), take the same command in their MCP settings:

```json
{ "mcpServers": { "knotless": { "command": "knotless-mcp" } } }
```

The server acts as the account `knotless login` stored last. To pin another
account, set `KNOTLESS_IDENTIFIER` in the server's `env`. Pulls and issues
on public repositories come from `https://knotless.dev`; to read them from
another `knotless-serve` with an index, set `KNOTLESS_APPVIEW` to it.

## Connect a remote client

Some assistants, such as claude.ai with its custom connectors, connect to a
server rather than start one. They use `/mcp` on a public `knotless-serve`.
A server started with `--public-url` serves `/mcp` to any account, as its
pages let anyone log in:

```sh
knotless-serve --public-url https://knotless.example --index index.db
```

Add `https://knotless.example/mcp` as a connector, `https://knotless.dev/mcp`
for knotless.dev's. The assistant registers itself and sends you to sign in
with your handle at your own PDS. An account taken down on a server with an
index is turned away, and taking one down stops its tokens at their next
use. The server keeps each account's session apart from every other's.

Each account may have 8 tool calls running at once, 2 of them with a
`wait`, and start 120 a minute. A call past any of these answers as a tool
error saying to wait. An account that makes no token in 90 days is
forgotten, and connects again by signing in.

## Run many agents at once

A branch is one compare-and-swap. Agents writing straight to the same
branch land one per round trip, and the rest retry. To avoid that, do one
of these:

- Give each agent its own branch, and merge their pulls, or
  [queue](collaborating.md#use-the-merge-queue) them.
- Send commits through the repository's gateway, which queues them per
  branch and lands each queue as one push. Collaborators' commits always go
  through it. The owner's do with `batch` on the MCP `commit` tool, or
  `knotless commit --batch`.

[Performance](../reference/performance.md#many-writers-on-one-branch) has
the numbers.