---
title: MCP tools reference
description: What your agent can do in Markloop: each tool, whether it reads or writes, its parameters and limits.
section: Reference
order: 10
---
<!-- Generated from the Markloop MCP server - do not edit. Source: internal_docs/_data/mcp-tools.json (build with internal_docs/build-docs.mjs). -->

Every tool your AI agent can call in Markloop. The server URL is `https://app.markloop.io/api/mcp`, and sign-in uses OAuth (see [Connect your AI tool](connect.md)). Your agent decides when to call these tools; you don't call them yourself.

> Markloop's tools never delete anything. Writes add a document, a version, or a comment. Republish adds a new version to a copy you published, so its readers see the new content right away; earlier versions are kept.

## Find documents

### Who am I

`markloop_whoami` · Read-only

Shows which workspaces and projects your agent can access.

### List projects

`markloop_list_projects` · Read-only

Lists the projects your agent can work in, with the workspace each one belongs to.

### List documents

`markloop_list_files` · Read-only

Lists the documents in a project, with open comment counts and when each one was last active.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | No | Project id from markloop_list_projects. |
| `since` | string (date-time) | No | ISO timestamp (e.g. when you last pulled) — adds `newMessagesSince` per file. |

## Read and compare

### Pull document with comments

`markloop_pull` · Read-only

Gets a document's current content and all open comment threads, so the agent can fix it.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `fileId` | string | Yes | Stable document id from markloop_list_files. |
| `since` | string (date-time) | No | ISO timestamp (e.g. when you last pulled) — marks new messages `isNew`. |
| `contentMode` | string (one of: `url`, `inline`) | No | `inline` returns the document content directly in the response — use when your environment cannot download the returned URL at all (sandboxed egress). |
| `contentOffset` | integer | No | Byte offset for the next inline chunk — pass the previous call's `nextOffset`. |
| `baseVersionId` | string | No | Pin the read to one version. |

### Get comment thread

`markloop_get_comment_thread` · Read-only

Gets one comment thread with all its replies and whether it is still open.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `fileId` | string | Yes | Stable document id from markloop_list_files/pull. |
| `commentId` | string | No | Thread root id (from a prior pull). |
| `number` | integer | No | Stable per-document thread number (from a prior pull/list). |

### List versions

`markloop_list_versions` · Read-only

Lists every version of a document and how many comments each version resolved.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | No | Project id from markloop_list_projects. |
| `fileId` | string | Yes | Stable document id from markloop_list_files/pull. |

### Get version

`markloop_get_version` · Read-only

Gets the content of any version of a document, so the agent can compare versions.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `fileId` | string | Yes | Stable document id from markloop_list_files/pull. |
| `versionNo` | integer | Yes | Version number from markloop_list_versions. |
| `contentMode` | string (one of: `url`, `inline`) | No | `inline` returns the document content directly in the response — use when your environment cannot download the returned URL at all (sandboxed egress). |
| `contentOffset` | integer | No | Byte offset for the next inline chunk — pass the previous call's `nextOffset`. |

## Publish and update

### Request upload

`markloop_request_upload` · Writes

Prepares an upload link, so the agent can send a file from disk without retyping it.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `filename` | string | Yes | File name, e.g. Product-Catalog.yaml. |
| `contentType` | string | No | e.g. text/html, application/json, application/yaml. Default: `"text/html"`. |
| `size` | integer | No | Byte size of the file, e.g. from `wc -c` — lets the server pick the right upload URL up front. |

### Create document

`markloop_create_file` · Writes

Adds a new document to a project and returns a link to view it.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `filename` | string | Yes | File name, e.g. proposal.html / data.json. |
| `folderPath` | string | No | Relative folder path, e.g. "specs/2026" or "a/b". |
| `contentType` | string | No | Defaults to text/html. |
| `content` | string | No | Inline content — only for tiny text generated right now (a few KB). |
| `intent` | string | No | intent from markloop_request_upload — preferred for any file on disk. |
| `size` | integer | No | Byte size of the uploaded file you uploaded via request_upload. |

### Push new version

`markloop_put_version` · Writes

Publishes a new version of a document and marks the comments it addressed.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `fileId` | string | Yes | Stable document id from list_files/pull. |
| `baseVersionId` | string | Yes | document.baseVersionId from the last pull. |
| `addressedCommentIds` | array of string | No | Comment ids you addressed in this version (the rest stay open). Default: `[]`. |
| `contentType` | string | No | — |
| `content` | string | No | Inline content — only for tiny text generated right now (a few KB). |
| `intent` | string | No | intent from markloop_request_upload — preferred for any file on disk. |
| `size` | integer | No | Byte size of the uploaded file you uploaded via request_upload. |

### Publish copy to another project

`markloop_publish_document` · Writes

Copies a document into another project, such as a client's, as a clean copy without your comments.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `sourceProjectId` | string | Yes | Project the source document lives in (from markloop_list_projects). |
| `fileId` | string | Yes | Stable source document id (from markloop_list_files). |
| `targetProjectId` | string | Yes | Project to publish the copy into (e.g. the client's project). |
| `atVersion` | integer | No | Source version number to publish (from markloop_list_versions). |
| `filename` | string | No | Name for the copy in the target. |
| `folderPath` | string | No | Relative folder path in the target, e.g. "client-acme". |

### Republish copy

`markloop_republish_document` · Replaces content

Updates a copy you published to another project with newer content. Replaces what its readers see.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `sourceProjectId` | string | Yes | Project the source document lives in. |
| `sourceFileId` | string | Yes | Stable id of the source document (the private original). |
| `targetProjectId` | string | Yes | Project the published copy lives in. |
| `targetFileId` | string | Yes | Stable id of the published copy (from publish's return / markloop_list_files). |
| `baseTargetVersionId` | string | Yes | document.baseVersionId from markloop_pull on the target (concurrency guard). |
| `atVersion` | integer | No | Source version number to publish (from markloop_list_versions). |

## Comment

### Create comment

`markloop_create_comment` · Writes

Leaves a new comment on a document, pinned to a quote or to an element on the page.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `fileId` | string | Yes | Stable document id from markloop_list_files/pull. |
| `text` | string | Yes | The comment body — what you want the reader to see. |
| `anchorType` | string (one of: `text`, `element`) | No | "text" = anchor to a quote (default), "element" = anchor to a CSS selector. Default: `"text"`. |
| `quote` | string | No | Exact text from the current version to anchor to (copy it verbatim from the pulled content, plain text, no tags). |
| `occurrence` | integer | No | 0-based index if the quote appears more than once. Default: `0`. |
| `selector` | string | No | CSS selector of the element. |
| `anchorX` | number | No | Element anchors only: relative x position inside the element (0..1). |
| `anchorY` | number | No | Element anchors only: relative y position inside the element (0..1). |

### Reply to comment

`markloop_reply_comment` · Writes

Replies to a comment thread, for example to explain a change, and can mark it resolved.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | string | Yes | Project id from markloop_list_projects/list_files. |
| `commentId` | string | Yes | — |
| `text` | string | Yes | The reply body (max 10000 characters). |
| `resolve` | boolean | No | Also mark the comment resolved (declined/handled). Default: `false`. |

## Limits

- **Document size:** up to 25 MB per document.
- **Sandboxed agents:** files up to 4 MB upload and download through Markloop's own domain, so they work from environments with restricted network access. Larger files go directly to storage.
- **Text sent inline:** up to 8 KB per call. The agent uploads anything larger as a file.
- **Workspaces:** you can give agents access to up to 10 workspaces.

Hourly limits on writes, counted per person across all connected workspaces:

| Action | Tools | Per hour | Per hour, trial workspace |
| --- | --- | --- | --- |
| New documents, versions and published copies | [Create document](#create-document), [Push new version](#push-new-version), [Publish copy to another project](#publish-copy-to-another-project), [Republish copy](#republish-copy) | 60 | 30 |
| Comments and replies | [Reply to comment](#reply-to-comment), [Create comment](#create-comment) | 120 | 60 |
| Upload links | [Request upload](#request-upload) | 120 | 60 |