MCP Examples

These are tool arguments, not direct requests to website API routes. Replace workspace slugs, resource IDs and keys after listing actual resources.

Search and cite

Call search_documents:

{ "organizationSlug": "my-workspace", "query": "positioning", "limit": 20 }

Inspect excerpts and URLs. Use get_document to read relevant bodies (returns Markdown including images and formatting), following continuation offsets. Summarize and cite returned URLs. An excerpt is not the entire document.

Read a topic

Call list_topics, then get_topic with a returned ID:

{ "organizationSlug": "my-workspace", "topicId": "TOPIC_ID" }

Use categories and planning dates to organize work. This does not schedule publishing.

Create a document

Check write scope, select a library with list_books, then call create_document:

{
  "organizationSlug": "my-workspace",
  "bookId": "BOOK_ID",
  "name": "Interview outline",
  "markdown": "# Interview outline\n\n- Use cases\n- Current difficulties",
  "idempotencyKey": "interview-outline-001"
}

After a timeout, retry with identical arguments and key. Open the returned URL and review the editor content.

Create and update an X draft

Call create_x_thread_draft:

{
  "organizationSlug": "my-workspace",
  "bookId": "BOOK_ID",
  "name": "Product notes",
  "posts": ["First observation", "Additional detail"],
  "idempotencyKey": "product-thread-001"
}

Read its document ID with get_x_thread. Follow nextOffset and merge all fragments by post ID, confirming the same updatedAt across segments. Use that actual timestamp in update_x_thread:

{
  "organizationSlug": "my-workspace",
  "documentId": "DOCUMENT_ID",
  "posts": ["Revised observation", "Additional detail"],
  "title": "Product notes",
  "expectedUpdatedAt": "2026-09-07T08:00:00.000Z"
}

title is optional. Omit it to leave the current title unchanged. An empty title, or one longer than 150 characters, is rejected and the draft is left untouched. Replace the example timestamp. On conflict, reread and reconcile other edits. Review the final draft on the website. These operations never publish.

Upload an image for documents or X threads

Upload an image in two steps:

1. Request a presigned PUT URL by calling create_image_upload:

{
  "organizationSlug": "my-workspace",
  "extension": "png",
  "fileSize": 1048576,
  "alt": "Architecture diagram",
  "idempotencyKey": "upload-arch-001"
}

The response includes uploadUrl (valid for 60 seconds), key, and publicUrl. The client directly HTTP PUTs the binary bytes to uploadUrl.

2. Confirm ledger accounting: after uploading bytes, call confirm_image_upload:

{
  "organizationSlug": "my-workspace",
  "key": "KEY_FROM_CREATE_IMAGE_UPLOAD",
  "alt": "Architecture diagram",
  "idempotencyKey": "confirm-arch-001"
}

The response includes ready-to-use Markdown syntax resource.markdown (e.g. ![Architecture diagram](/org/.../file.png) using a relative storage path). Pass it to create_document so the editor projects a real image node.

3. To attach the confirmed image to an X thread draft post: call attach_image_to_x_thread:

{
  "organizationSlug": "my-workspace",
  "documentId": "DOCUMENT_ID",
  "key": "KEY_FROM_CREATE_IMAGE_UPLOAD",
  "expectedUpdatedAt": "2026-09-07T08:00:00.000Z",
  "postIndex": 0,
  "alt": "Architecture diagram"
}

Each post supports up to 4 images.