> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> Every tool the Mesa MCP server exposes, the access level it requires, and what it does.

The Mesa MCP server exposes 22 tools. The **Access** column shows the level each tool needs (see [Authentication](/content/reference/mcp/authentication)). Your agent fetches each tool's full input and output schema automatically when it connects, so this page focuses on what each tool does.

Tools marked **Destructive** move or delete state that other agents may be using, so they are **fenced** with optimistic concurrency. A fenced call passes the value it last read, and if the bookmark has moved in the meantime the call is rejected, the agent re-reads and retries, and concurrent agents can't silently overwrite each other's work.

## Bookmarks

| Tool               | Access | Description                                                                                                                                                                                         |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bookmark_list`    | read   | List a repository’s bookmarks and the commit each one points at.                                                                                                                                    |
| `bookmark_resolve` | read   | Look up a bookmark by name: the change and commit it currently points at.                                                                                                                           |
| `bookmark_create`  | write  | Create a bookmark pointing at a commit.                                                                                                                                                             |
| `bookmark_move`    | write  | **Destructive.** Move a bookmark to a new commit, how finished work is published, e.g. advancing `main` to a change’s latest commit. Fenced: rejected if the bookmark moved since it was last read. |
| `bookmark_delete`  | write  | **Destructive.** Delete a bookmark. Fenced, and requires explicit confirmation.                                                                                                                     |
| `bookmark_merge`   | write  | **Destructive.** Merge a source bookmark into a target bookmark, optionally deleting the source afterwards. Fenced.                                                                                 |

## Changes

| Tool             | Access | Description                                                                                                                                                                                     |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `change_get`     | read   | Fetch a change by id.                                                                                                                                                                           |
| `change_list`    | read   | List the changes reachable from the default bookmark, paginated.                                                                                                                                |
| `change_history` | read   | A change’s evolution log: every snapshot it has passed through, each pinned to a commit and timestamp.                                                                                          |
| `change_create`  | write  | Start a new change on top of a bookmark or an existing change.                                                                                                                                  |
| `change_write`   | write  | Write files to a repository: creates a change (or continues one) and snapshots the files into a commit. Edits too large for one call can be staged across several calls and committed together. |

## Commits

| Tool                  | Access | Description                                                                                                                                    |
| --------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `commit_get`          | read   | Fetch a commit by OID.                                                                                                                         |
| `commit_list`         | read   | List the commit history reachable from a ref, paginated.                                                                                       |
| `commit_list_changes` | read   | List the changes reachable from a specific commit, like `change_list`, but starting from any point in history instead of the default bookmark. |

## Content & diffs

| Tool           | Access | Description                                                                                                |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `diff`         | read   | Diff two changes or two commits.                                                                           |
| `dir_list`     | read   | List one level of a directory at a view: a change, commit, or bookmark (defaults to the default bookmark). |
| `path_stat`    | read   | Stat a file, directory, or symlink at a view.                                                              |
| `path_content` | read   | Read file content at a view. Large files are read in pages.                                                |

## Repositories

| Tool          | Access | Description                                                                                                       |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `repo_create` | write  | Create a repository in your organization, with its default bookmark (`main` unless overridden) ready to write to. |
| `repo_get`    | read   | Fetch a repository by name.                                                                                       |
| `repo_list`   | read   | List the repositories in your organization.                                                                       |

## Guide

| Tool         | Access | Description                                                                             |
| ------------ | ------ | --------------------------------------------------------------------------------------- |
| `mesa_guide` | read   | The server’s built-in usage guide, the same guide your agent receives when it connects. |