MCP tools reference
What your agent can do in Markloop: each tool, whether it reads or writes, its parameters and limits.
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). 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
Shows which workspaces and projects your agent can access.
List projects
Lists the projects your agent can work in, with the workspace each one belongs to.
List documents
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
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
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
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
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
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
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
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
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
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
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
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, Push new version, Publish copy to another project, Republish copy | 60 | 30 |
| Comments and replies | Reply to comment, Create comment | 120 | 60 |
| Upload links | Request upload | 120 | 60 |