MCP tools.
10 tools: 5 read and 5 write. This page is generated from the server's own tool list, so it matches what tools/list returns. For setup, see the MCP server guide.
Before you call a tool
The endpoint is https://pinthread.dev/mcp. Send an agent token as Authorization: Bearer ptk_…. The token belongs to one project, so every tool works on that project only.
Read tools work with any token: whoami, list_threads, get_thread, list_events, get_page_context. Write tools need a write token: reply_thread, create_thread, resolve_thread, reopen_thread, mark_suggestion_applied. A read token that calls a write tool gets a tool error, not a protocol error.
Tool results are JSON text. Every tool takes an optional branch that defaults to shared, except whoami.
Server instructions
On initialize the server sends these instructions to the client:
Read design comments with list_threads and get_page_context. React to new comments with list_events and its cursor. Reply with reply_thread. Resolve a thread only after the fix is merged.Read tools
whoami
Any token. Show the project, repository, token name and scope (read or write) this connection uses.
No arguments.
list_threads
Any token. List design comment threads for the project, newest activity last. Use status 'open' for work still to do.
| Argument | Type | Required | Meaning |
|---|---|---|---|
status | open | resolved | all | No | Default open. |
page | string | No | Only threads on this page path, such as /pricing. |
since | number | No | Only threads updated after this Unix time in milliseconds. |
limit | number | No | Maximum threads to return. Default 50, maximum 300. |
branch | string | No | Comment scope. Defaults to "shared". |
get_thread
Any token. Read one thread with every comment, author and reaction. Includes its attachments (log and metadata text inline; screenshots, video and replay as links that expire in 15 minutes) and, for a suggested text edit, a suggestion with old, new and selector.
| Argument | Type | Required | Meaning |
|---|---|---|---|
thread_id | string | Yes | Thread id from list_threads. |
branch | string | No | Comment scope. Defaults to "shared". |
list_events
Any token. Read new comment activity (new threads and replies) after a cursor, oldest first. Pass the cursor from the last call as `since`; use 'latest' to start from now. Poll this to react to new design comments without re-reading every thread.
| Argument | Type | Required | Meaning |
|---|---|---|---|
since | string | No | Cursor from the previous call, or 'latest'. Omit to read from the start. |
limit | number | No | Maximum events to return. Default 100, maximum 200. |
branch | string | No | Comment scope. Defaults to "shared". |
get_page_context
Any token. Return the open threads on one page, with their anchors, attachments and suggested edits, so you know which elements the comments point at.
| Argument | Type | Required | Meaning |
|---|---|---|---|
page | string | Yes | Page path, such as /pricing. |
branch | string | No | Comment scope. Defaults to "shared". |
Write tools
reply_thread
Write token. Add a reply to a thread as this agent. Needs a write token.
| Argument | Type | Required | Meaning |
|---|---|---|---|
thread_id | string | Yes | Thread id from list_threads. |
body | string | Yes | Reply text, up to 4000 characters. |
branch | string | No | Comment scope. Defaults to "shared". |
create_thread
Write token. Start a new thread on a page. The anchor says where the comment points. Needs a write token.
| Argument | Type | Required | Meaning |
|---|---|---|---|
page | string | Yes | Page path, such as /pricing. |
body | string | Yes | Comment text, up to 4000 characters. |
anchor | object | Yes | Copy the anchor of an existing thread on the page, or give selector, text, x, y, width, height (0 to 1, relative to the element), pageX, pageY and viewportWidth. Add suggestion {old, new} to propose an exact text edit. |
branch | string | No | Comment scope. Defaults to "shared". |
resolve_thread
Write token. Mark a thread resolved. Needs a write token.
| Argument | Type | Required | Meaning |
|---|---|---|---|
thread_id | string | Yes | Thread id from list_threads. |
branch | string | No | Comment scope. Defaults to "shared". |
reopen_thread
Write token. Reopen a resolved thread. Needs a write token.
| Argument | Type | Required | Meaning |
|---|---|---|---|
thread_id | string | Yes | Thread id from list_threads. |
branch | string | No | Comment scope. Defaults to "shared". |
mark_suggestion_applied
Write token. Mark a thread's suggested text edit as applied after you changed the code. Adds a note comment and resolves the thread. Needs a write token.
| Argument | Type | Required | Meaning |
|---|---|---|---|
thread_id | string | Yes | Thread id from list_threads. |
note | string | No | What you changed, up to 1000 characters. |
branch | string | No | Comment scope. Defaults to "shared". |
Next
The HTTP API reference covers the JSON-RPC envelope and the plain REST routes behind these tools.