# MCP for AI agents

Connect Claude, Cursor or your own agent to Side Space over the Model Context Protocol. It signs in through the browser, and every tool respects the token's scopes and spaces.

The server runs a remote MCP server at `/mcp` (streamable HTTP). An agent connected to it can search a space, understand a video from its metadata without downloading it, write and edit notes and results, organize and share files, look back in time, run AI actions, answer review comments and work in a fork.

Just want to use Side Space from Claude? See [Use it in Claude](/docs/claude).

## Connect

Clients that support MCP authorization (Claude, Claude Code, Cursor and others) only need the address:

```sh
claude mcp add --transport http side https://side.example.com/mcp
```

The first time, the client opens a browser. You sign in to Side Space with your email code, choose what it may do (by default read and write files, comment and run actions) and which spaces it may reach, and click **Allow**. The client then holds a one-hour token that it refreshes by itself. It shows up in `sidespace token list` as `app:…`, and `sidespace token revoke` disconnects it at any time.

On claude.ai, add the same address as a custom connector.

### With a token instead

For [agent members](/docs/authentication#agents) and unattended agents, skip the browser and send a token:

```sh
sidespace token create claude --agent "Clip Tagger" --scope files:read --scope "sidecars:write:x-tagger.*"
claude mcp add --transport http side https://side.example.com/mcp \
  --header "Authorization: Bearer ssp_…"
```

## Tools

### Find and read

| Tool | Does |
|---|---|
| `list_spaces` | The spaces the token reaches |
| `search` | Names, metadata, transcripts and comments, or by meaning; returns moments in media |
| `list_folder` | A folder's files and folders; with `as_of`, what it held then |
| `describe_file` | What a file is, without downloading it: type, versions and who saved them, every sidecar (tags, AI prompt, media facts, transcript) and which previews exist |
| `read_text` | A text file up to 1 MiB; with `as_of`, as it was then |
| `get_sidecar` | Read metadata |
| `recent_changes` | What happened in a space lately, and who did it |

### Write and organize

| Tool | Does |
|---|---|
| `write_text` | Write a whole text file; creates folders, and adds a version when the file exists |
| `edit_text` | Replace an exact piece of text (it must be unique, or pass `replace_all`) in a file up to 16 MiB; only the change is sent |
| `append_text` | Add text at the end; creates the file when it's missing |
| `put_sidecar` | Write metadata |
| `make_folder` | Make a folder, and any folders on the way |
| `move` | Move or rename; makes missing folders on the way, and refuses a path that is taken |
| `delete` | Move to the trash (30 days). Marked destructive; its description asks the agent to confirm with you first |
| `share_link` | A link to a file or folder: view, review comments, watch-only or upload, with a password and expiry. Needs `shares:manage` |
| `request_files` | Ask people without an account for files ("Ep03 dailies, by Friday"); each sender's files land in a subfolder named after them. Needs `shares:manage` |

### Versions and the past

| Tool | Does |
|---|---|
| `list_versions`, `label_version`, `compare_versions`, `restore_version` | History, names ("Client cut"), what changed, going back one file |
| `rewind_folder` | Put a whole folder back as it was at a moment; dry run first. See [History](/docs/history) |

### Review, forks and actions

| Tool | Does |
|---|---|
| `list_comments`, `add_comment`, `resolve_comment` | Read review notes, answer them, mark them done |
| `fork_space`, `fork_changes`, `apply_fork` | Work in a sandbox and bring back what to keep |
| `list_actions`, `run_action`, `get_run` | Transcribe, tag or convert a file and wait for the result (60 s by default, up to 300) |

- Arguments use a space name (or id) and a path such as `/Ep01/Shots/a.mov`, and answers use paths too.
- Versions can be given as an id, a number (`3`, `v3`) or a name. `compare_versions` with no versions compares the current version with the one before.
- `as_of` is a time, a duration ago (`-2h`) or a journal seq.
- `edit_text` and `append_text` take `if_version_id`, and fail if the file has been saved since that version.
- Tools that answer structured data return it as `structuredContent` too.
- Every tool is checked against the token's scopes and spaces. When something is not allowed or not there, the tool returns an error the model can read and adjust to.
- Changes are recorded for the member behind the token; an agent's appear with the **Agent** badge.

## Good habits for agents

The server's `/llms.txt` gives agents most of these rules; they're worth putting in your own prompts too:

- Saving never destroys: every save is a new version, and any version can be restored.
- Prefer writing results to a sidecar over writing new files next to the original.
- Read a file's sidecars before running an action: the transcript or tags may already exist.
- Ask a person before deleting, moving many files, or changing members and shares.
- Use `edit_text` or `append_text` for small changes to a long file instead of writing all of it again.
- Before `rewind_folder`, run it with `dry_run` and show the person the list.
- For larger reorganizations, work in a fork and show the person `fork_changes` before applying.