# MCP server for AI agents

`ownbackend mcp` is an [MCP](https://modelcontextprotocol.io) server that
runs on your device. With it, an AI agent (Claude Code, Cursor, Claude
Desktop and others) can create your backend, link the device to it, and
design the data: collections, fields and the rules for who may read and
write. Account actions still need you: creating a backend ends with you
approving it in the browser.

## Set it up

Install ownbackend first (see the [Quickstart](/docs/quickstart.md)). The
server works on one backend: the data in the project's `.ownbackend` folder,
given with `--dir`. `ownbackend serve` prints the exact command for its
folder; or run these in your project folder.

**Claude Code:**

```sh
claude mcp add ownbackend -- ownbackend mcp --dir "$PWD/.ownbackend/data"
```

**Cursor** (`.cursor/mcp.json` in the project) or **Claude Desktop**
(`claude_desktop_config.json`), with the folder written out:

```json
{
  "mcpServers": {
    "ownbackend": {
      "command": "ownbackend",
      "args": ["mcp", "--dir", "/path/to/your/project/.ownbackend/data"]
    }
  }
}
```

**Any other MCP client** that runs servers over stdio: the command is
`ownbackend mcp --dir <project>/.ownbackend/data`. If the client can't find
`ownbackend`, use its full path (`~/.local/bin/ownbackend` after the install
script).

## What the agent can do

| Tool | What it does |
|---|---|
| `status` | Whether this device is linked to a backend, its public URL, whether the server runs, a pairing waiting for approval, and the next step. |
| `create_backend` | Starts creating a backend with a suggested name; returns a link for you to open, sign in and approve. |
| `check_pairing` | Whether you approved; once you have, the device is linked. |
| `connect` | Links the device with a connect code you got in the dashboard (the server must be stopped). |
| `list_collections`, `get_collection` | The data model: collections, fields, rules. |
| `create_collection`, `update_collection`, `delete_collection` | Change it. |
| `list_records`, `create_record`, `update_record`, `delete_record` | Data, e.g. for testing. |

The order an agent follows:

1. `status`.
2. Not linked yet: `create_backend`, then you approve in the browser, then
   `check_pairing`. Or `connect` with a code from the dashboard.
3. Start the backend: `ownbackend serve` in the project folder (or
   `ownbackend service install` to keep it running). The data tools need it
   running.
4. Shape the data, then build the frontend against
   `https://<name>.ownbackend.app` into `dist/`
   ([Using your backend from an app](/docs/api.md)).

## What stays with you

- Approving a new backend, in the browser, signed in.
- The device token and the backup recovery code: the MCP server never shows
  them to the agent. See the recovery code yourself with
  `ownbackend backup recovery-code`.
- The tools act as an admin of your backend (the agent gets its own admin
  account, `agent@ownbackend.local`, on this device only). Admin access never
  works through the public address.