Tool reference

The two MySpec MCP servers share 43 tools in nine groups, with the same names wherever they do the same thing. Two more tools exist on only one server:

• download_spec_file is local server only, because it saves files to your disk.
• list_trashed_spec_files is remote server only and deprecated.

In the tables, Changes data marks the tools that create, change or delete something in MySpec. They need a read and write API token or a connection with write access (except stream tokens; see Stream tokens). Every other tool only reads. Every tool also works within your role on the project; see Project roles.

Projects

Spec files

Trash

Attachments

Sessions

No session tool returns the chat conversation itself.

Artifacts

Stream tokens

A Read only API token can also create and revoke stream tokens, because a stream token only reads. A connector connected without write access cannot. See Stream tokens for how to use them.

Comments

Tasks

The task tools work on a project’s task board: the checkbox tasks in its tasks.md files. See Tasks.

• update_tasks applies the same change to every task you pass. A field you leave out stays as it is, and null clears it. Labels are added and removed, not replaced. One unknown task id fails the whole call.
• A relationship says how a task stands to another: it blocks the other task, it is blocked_by the other task, or the two are related. Each list_tasks task lists them as {type, task_id}. In update_tasks, add_relationships sets them and remove_relationships takes task ids to unlink. Two tasks have one relationship at most, so setting one replaces the old one, and the other task shows the inverse.
• set_task_status can partly succeed: a file it can’t write fails only its own tasks, and the result gives an outcome for each task. Pass expected_versions with the content_version values from list_tasks, so a file that changed since you listed it is not written.
• The task tools work only where the task board is available. Elsewhere they fail with “the task board is turned off in this MySpec environment”.

Project roles

Each tool works within your project role, and never does more than you can do in the web app:

• list_projects and get_project show your role on each project as viewer_role: read, write or admin.
• list_projects leaves out projects you have no role on, and other tools answer as if those projects do not exist.
• create_project works whatever your role, and gives you admin on the new project.
• A Read only API token, or a connection without write access, acts as read on every project. Its tools that change data fail with the read-only error.

A tool that needs more than your role fails with a message like this one:

update_spec_file failed: permission denied — this action needs the write role on the project; you have read. Ask a project admin for access.

A new token will not help. Ask someone with admin on the project to raise your role. See Troubleshooting.

Edit safely with content_version

Several people and AI sessions can work on the same project at once. To avoid overwriting someone else’s work:

1. Read the file with get_spec_file or read_spec_file. Both return a content_version.
2. Pass that value as expected_version to update_spec_file.
3. If someone saved the file in the meantime, the update is rejected and their version is kept. The error says who changed it and when. Read the file again, combine the changes, and update with the new content_version.

Do not resend the same content after a conflict: that would undo the other person’s work. content_version is not the same as the revision count.

The remote server always requires expected_version. The local server accepts an update without it, but a project can be set up to reject such updates, so always pass it.

Pagination

Lists

List tools take limit and offset. They return total and, while more records remain, next_offset: pass it as offset to get the next page. The local server’s list_projects returns no next_offset; page on with offset until you have total projects. A limit above the maximum is reduced to the maximum, except on the local server’s list_projects, which refuses it.

list_tasks returns total_tasks instead of total, and refuses a limit above 500.

list_spec_file_comments returns at most 100 threads and shortens each comment to 1,000 characters. Filter by status to see fewer threads in full.

Reading files by line

read_spec_file, read_attachment (for text) and read_artifact_file read a window of lines:

• offset is the first line to read, starting at 1.
• limit is the number of lines, at most 2,000 (the default). One response holds at most 1 MiB.
• The result includes total_lines, truncated and, when more lines remain, next_offset.

read_spec_file refuses binary files and files over 8 MiB. On the local server, use download_spec_file for those. On the remote server, open them in the web app.

Start a session from your agent

start_spec_session lets your coding agent start a MySpec session for you, with an opening message it writes from what it knows about your code and your goal.

• One call starts one real session, and that session uses AI, just like one you start in the web app. Call it once per goal. If the call times out, check list_spec_sessions before trying again, or you may create a duplicate.
• It waits for the first reply, for up to 75 seconds, then returns. If the first reply is not finished by then, it returns anyway and the reply finishes in the background.
• It needs write access: a read and write API token, or a connection with write access, and the write role on the project. With read-only access, no session is created.
• For Brownfield workflows, start the local server’s reverse command first and keep it running, so the session can read your code. See Work on an existing codebase.
• A Generate session runs at Full spec depth. The tool has no spec depth argument. When you continue the session in the web app, the level picked there applies from your next message. See Spec depth.

Arguments

An unknown workflow_id, or one that does not match mode, is rejected before anything is created. So is an attachment or spec file id that does not belong to the project.

Result

The agent’s job ends with handing over session_url. The person continues the session in MySpec; the agent should not try to answer MySpec’s questions itself.

How artifacts work

An artifact is a set of files that MySpec stores and versions as one unit, such as an HTML mockup made of index.html, styles.css and app.js.

• create_artifact creates revision 1. An artifact can hold at most 50 files, 2 MiB per file and 10 MiB per revision. Its slug must be unique in the project.
• write_artifact_revision adds a revision. Without base_revision, the files you send become the whole artifact. With base_revision, you send only the changed files, plus the paths to drop in remove.
• Revisions never change once written. By default, only the 50 newest are kept; rolling back to an older one that is no longer kept fails with “not found”.
• rollback_artifact restores an earlier revision by adding a new revision with its files. History is never rewritten.
• To avoid overwriting someone else’s revision, pass the current revision_count from get_artifact or list_artifacts as expected_version. If the artifact has moved on, the write is rejected; read it again and retry.

Rules for comments

• No tool can resolve, reopen or re-attach a thread. Agents can read, add, reply, and edit or delete their own comments. Deciding that a discussion is finished stays with people. See Comments.
• To start a thread, pass the passage as anchor_quote, copied exactly from the file. MySpec finds it in the current text. Do not send character positions. If the passage appears more than once, add a few words before or after it in anchor_prefix or anchor_suffix.
• update_spec_file_comment takes the comment’s own content_version as expected_version, not the file’s.
• delete_spec_file_comment has three outcomes. A reply disappears. A first comment that has replies is replaced by a “deleted” placeholder, so the replies still make sense. A first comment with no replies deletes the whole thread.
• On a file in the Trash Bin you can read, edit and delete comments, but you cannot start threads or reply.
• MySpec records comments and spec file changes made through these tools as AI work. In the web app, comments written by an agent show as MySpec AI.

Limit the tools an agent sees

On the remote server, the optional X-MCP-Tools header limits the tools your agent sees. See Remote MCP server.