Reference

MCP tools

Every tool the MiraDock MCP server exposes - what they do, how to call them, and what they return.

Overview

MCP clients call these tools through POST /mcp. The server registers the tools in lib/mcp/server.ts. Use the connect guides to wire a client.

Authentication

The route requires an Authorization bearer value. Read tokens authenticate read tools. Write tokens authenticate write tools. OAuth access tokens are accepted for write tools only when they include the mcp:write scope. Generate MCP tokens in /app/mcp. Write tokens may be bucket-restricted; when allowed_bucket_ids is set, mutation tools can only target those bucket IDs. Writes outside that set, plus bucket creation and other non-bucket-scoped writes, return a structured 403 error. Read tools are unchanged.

Tool reference

Workspaces

search_buckets

Search across workspaces that this MCP connection can read. Anonymous clients see public workspaces only; authenticated clients also see the token owner's private workspaces.

Auth	Parameters	Returns	Errors
read token	query: string; limit?: integer <= 50	JSON workspace list	unauthorized, rate_limited, internal

json

{
  "name": "search_buckets",
  "arguments": {
    "query": "..."
  }
}

list_buckets

List workspaces available to the client. Use visibility='public' for public-only results, 'private' for authenticated owner-private workspaces, or 'all' for everything readable.

Auth	Parameters	Returns	Errors
read token	visibility?: 'public' \| 'private' \| 'all'; owned_by_me?: boolean	JSON workspace list	unauthorized, rate_limited, internal

json

{
  "name": "list_buckets",
  "arguments": {
    "visibility": "..."
  }
}

get_bucket

Return metadata, owner identity, page/source counts, recent activity, page_kind_breakdown, top_entities, and top_concepts for a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket?: string; deprecated workspace slug alias?: string; owner_username?: string	Workspace metadata	bad_request, not_found, unauthorized, rate_limited

json

{
  "name": "get_bucket",
  "arguments": {
    "bucket": "..."
  }
}

create_bucket

Create a new private or public workspace owned by the write-token user. Add pages with push_web_page, push_markdown_file, or push_markdown.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	title?: string; name?: string; slug?: string; visibility?: 'private' \| 'public'; discoverable?: boolean; description?: string; tags?: string[]; topic_tag_slugs?: string[]	Created workspace	validation_error, tier_limit_exceeded, unauthorized, permission_denied, rate_limited

json

{
  "name": "create_bucket",
  "arguments": {
    "title": "..."
  }
}

fork_bucket

Create a private or public copy of a public workspace that allows forks. The fork keeps upstream attribution and tracking.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace path: owner_username/workspace_slug; new_name?: string \| null; visibility?: 'private' \| 'public'	Forked workspace metadata	not_found, forbidden, validation_error, unauthorized, permission_denied

json

{
  "name": "fork_bucket",
  "arguments": {
    "legacy workspace path": "..."
  }
}

update_bucket_metadata

Owner-only workspace metadata update for name, description, visibility, discoverability, and topic tags.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace path: owner_username/workspace_slug; name?: string; description?: string \| null; visibility?: 'private' \| 'public'; discoverable?: boolean; add_topics?: string[]; remove_topics?: string[]	Updated workspace metadata	not_found, permission_denied, validation_error

json

{
  "name": "update_bucket_metadata",
  "arguments": {
    "legacy workspace path": "..."
  }
}

list_my_buckets

List workspaces the write-token user can push to, including owned workspaces and Editor collaborations.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	include collaborations?: boolean; visibility?: 'private' \| 'public'; tag?: string	Writable workspace list	unauthorized, permission_denied, rate_limited

json

{
  "name": "list_my_buckets",
  "arguments": {
    "include collaborations": "..."
  }
}

update_bucket

Update workspace title, description, visibility, or tags.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; title?: string; description?: string \| null; visibility?: 'private' \| 'public'; tags?: string[]	{ bucket }	not_found, permission_denied, validation_error

json

{
  "name": "update_bucket",
  "arguments": {
    "bucket": "..."
  }
}

delete_bucket

Delete a workspace owned by the write-token user.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ ok: true }	not_found, permission_denied

json

{
  "name": "delete_bucket",
  "arguments": {
    "bucket": "..."
  }
}

set_cover_web_page

Set the cover Web page for a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; web_page: string	{ bucket }	not_found, permission_denied

json

{
  "name": "set_cover_web_page",
  "arguments": {
    "bucket": "..."
  }
}

set_grounding_bucket

Set a session-scoped active workspace for later get_web_page and list_web_pages calls that omit a workspace target.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace path: owner_username/workspace_slug	{ activeWorkspacePath }	not_found, unauthorized, permission_denied

json

{
  "name": "set_grounding_bucket",
  "arguments": {
    "legacy workspace path": "..."
  }
}

Web pages

list_web_pages

List page titles, slugs, summaries, content_type, page_kind values, last_updated timestamps, and claim_count values in a readable workspace. Use sort='alphabetical' when an agent needs deterministic navigation.

Auth	Parameters	Returns	Errors
read token	bucket?: string; deprecated workspace slug alias?: string; owner_username?: string; limit?: integer <= 100; sort?: 'alphabetical' \| 'recent'	Workspace page list	not_found, unauthorized, rate_limited

json

{
  "name": "list_web_pages",
  "arguments": {
    "bucket": "..."
  }
}

get_web_page

Read a workspace page with content_type plus structured grounding fields. HTML pages return sanitized HTML in native mode or extracted text in text mode.

Auth	Parameters	Returns	Errors
read token	bucket?: string; web_page?: string; deprecated workspace slug alias?: string; page_slug?: string; format?: 'native' \| 'text'; owner_username?: string	Workspace page content	bad_request, not_found, unauthorized

json

{
  "name": "get_web_page",
  "arguments": {
    "bucket": "..."
  }
}

search_web_pages

Search page titles, summaries, and text-readable page content across readable workspaces.

Auth	Parameters	Returns	Errors
read token	query: string; deprecated workspace slug alias?: string; owner_username?: string; limit?: integer <= 50	{ pages: McpPageSearchResult[] }	unauthorized, rate_limited

json

{
  "name": "search_web_pages",
  "arguments": {
    "query": "..."
  }
}

get_web_page_links

Return a page's outbound [[Page]] links and inbound backlinks so agents can walk the workspace graph.

Auth	Parameters	Returns	Errors
read token	deprecated workspace slug alias?: string; page_slug: string; owner_username?: string	{ outbound, inbound }	not_found, unauthorized

json

{
  "name": "get_web_page_links",
  "arguments": {
    "deprecated workspace slug alias": "..."
  }
}

push_web_page

Create or update one HTML Web page. Raw HTML is sanitized server-side before storage. Omit a workspace target to save into the token owner's default workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy workspace id/path fields?: uuid\|string; content_type?: 'markdown' \| 'html'; page_title?: string \| null; page_slug?: string \| null; page_content: string <= 1 MiB	{ part, action, warnings, sanitization_warnings? }	validation_error, tier_limit_exceeded, unauthorized, permission_denied, rate_limited

json

{
  "name": "push_web_page",
  "arguments": {
    "bucket": "..."
  }
}

delete_web_page

Delete a page from a workspace the write-token user owns or edits.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; web_page?: string; legacy workspace path?: string; page_slug?: string	{ ok: true }	bad_request, not_found, permission_denied

json

{
  "name": "delete_web_page",
  "arguments": {
    "bucket": "..."
  }
}

list_web_page_versions

List saved versions for a Web page.

Auth	Parameters	Returns	Errors
read token	bucket: string; web_page: string	{ versions: PartVersion[] }	not_found, unauthorized

json

{
  "name": "list_web_page_versions",
  "arguments": {
    "bucket": "..."
  }
}

get_web_page_version

Read a specific saved Web page version.

Auth	Parameters	Returns	Errors
read token	bucket: string; web_page: string; version: positive integer	{ version, content }	not_found, unauthorized

json

{
  "name": "get_web_page_version",
  "arguments": {
    "bucket": "..."
  }
}

restore_web_page_version

Restore a previous Web page version.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; web_page: string; version: positive integer	{ part }	not_found, permission_denied, validation_error

json

{
  "name": "restore_web_page_version",
  "arguments": {
    "bucket": "..."
  }
}

Artifacts (markdown files)

push_markdown_file

Create or update one Markdown file using a complete Markdown document with YAML front matter. Omit a workspace target to save into the token owner's default workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy workspace id/path fields?: uuid\|string; page_title?: string \| null; page_slug?: string \| null; page_content: string <= 1 MiB	{ part, action, warnings }	invalid_front_matter, invalid_slug, validation_error

json

{
  "name": "push_markdown_file",
  "arguments": {
    "bucket": "..."
  }
}

push_markdown

Create or update one Markdown artifact. Provide a workspace slug to save it in a workspace; omit it for standalone.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; page_title?: string \| null; page_slug?: string \| null; page_content: string <= 1 MiB	{ part, action, warnings }	invalid_front_matter, invalid_slug, validation_error

json

{
  "name": "push_markdown",
  "arguments": {
    "bucket": "..."
  }
}

get_markdown_file

Read one Markdown file from a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket: string; markdown_file: string	{ part }	not_found, unauthorized

json

{
  "name": "get_markdown_file",
  "arguments": {
    "bucket": "..."
  }
}

list_markdown_files

List Markdown files in a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket: string	{ parts: BucketPart[] }	not_found, unauthorized

json

{
  "name": "list_markdown_files",
  "arguments": {
    "bucket": "..."
  }
}

delete_markdown_file

Delete a Markdown file from a writable workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; markdown_file: string	{ ok: true }	not_found, permission_denied

json

{
  "name": "delete_markdown_file",
  "arguments": {
    "bucket": "..."
  }
}

list_markdown_file_versions

List saved versions for a Markdown file.

Auth	Parameters	Returns	Errors
read token	bucket: string; markdown_file: string	{ versions: PartVersion[] }	not_found, unauthorized

json

{
  "name": "list_markdown_file_versions",
  "arguments": {
    "bucket": "..."
  }
}

get_markdown_file_version

Read a specific saved Markdown file version.

Auth	Parameters	Returns	Errors
read token	bucket: string; markdown_file: string; version: positive integer	{ version, content }	not_found, unauthorized

json

{
  "name": "get_markdown_file_version",
  "arguments": {
    "bucket": "..."
  }
}

restore_markdown_file_version

Restore a previous Markdown file version.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; markdown_file: string; version: positive integer	{ part }	not_found, permission_denied

json

{
  "name": "restore_markdown_file_version",
  "arguments": {
    "bucket": "..."
  }
}

Micro DBs

push_micro_db

Create or update the Micro DB artifact shell.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; title?: string \| null; slug?: string \| null; visibility?: 'private' \| 'public'; summary?: string \| null	{ part }	validation_error, permission_denied

json

{
  "name": "push_micro_db",
  "arguments": {
    "bucket": "..."
  }
}

list_micro_db_tables

List tables in the micro-database attached to a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket: string	{ tables: MicroDbTable[] }	not_found, unauthorized

json

{
  "name": "list_micro_db_tables",
  "arguments": {
    "bucket": "..."
  }
}

get_micro_db_schema

Return one Micro DB table and its typed columns.

Auth	Parameters	Returns	Errors
read token	bucket: string; table: string	{ table, columns }	not_found, unauthorized

json

{
  "name": "get_micro_db_schema",
  "arguments": {
    "bucket": "..."
  }
}

query_micro_db_rows

Query rows with structured AND filters, validated column slugs, typed comparisons, sorting, limit, and offset.

Auth	Parameters	Returns	Errors
read token	bucket: string; table: string; filter?: MicroDbFilter[]; sort?: MicroDbSort[]; limit?: integer <= 500; offset?: integer >= 0	{ rows, total? }	not_found, validation_error

json

{
  "name": "query_micro_db_rows",
  "arguments": {
    "bucket": "..."
  }
}

get_micro_db_row

Read one row from a Micro DB table by id.

Auth	Parameters	Returns	Errors
read token	bucket: string; table: string; row_id: uuid	{ row }	not_found, unauthorized

json

{
  "name": "get_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

create_micro_db_table

Create a typed table in a writable Micro DB.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; name: string; slug?: string; description?: string \| null; columns: MicroDbColumnDef[]	{ table }	validation_error, permission_denied

json

{
  "name": "create_micro_db_table",
  "arguments": {
    "bucket": "..."
  }
}

update_micro_db_table

Update Micro DB table metadata.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; name?: string; description?: string \| null; position?: integer	{ table }	not_found, validation_error

json

{
  "name": "update_micro_db_table",
  "arguments": {
    "bucket": "..."
  }
}

delete_micro_db_table

Snapshot the Micro DB, then delete a table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string	{ ok: true, snapshot? }	not_found, permission_denied

json

{
  "name": "delete_micro_db_table",
  "arguments": {
    "bucket": "..."
  }
}

add_micro_db_column

Add a typed column to a Micro DB table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; column_def: MicroDbColumnDef	{ column }	validation_error, permission_denied

json

{
  "name": "add_micro_db_column",
  "arguments": {
    "bucket": "..."
  }
}

update_micro_db_column

Update a Micro DB column definition.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; column: string; patch: Partial<MicroDbColumnDef>	{ column }	not_found, validation_error

json

{
  "name": "update_micro_db_column",
  "arguments": {
    "bucket": "..."
  }
}

delete_micro_db_column

Snapshot the Micro DB, then delete a column definition.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; column: string	{ ok: true, snapshot? }	not_found, permission_denied

json

{
  "name": "delete_micro_db_column",
  "arguments": {
    "bucket": "..."
  }
}

insert_micro_db_row

Validate and insert one row into a Micro DB table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; data: object	{ row }	validation_error, permission_denied

json

{
  "name": "insert_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

insert_micro_db_rows

Validate and insert rows in one all-or-nothing bulk write.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; rows: object[]	{ rows }	validation_error, permission_denied

json

{
  "name": "insert_micro_db_rows",
  "arguments": {
    "bucket": "..."
  }
}

update_micro_db_row

Patch one Micro DB row; data keys merge into the existing JSON row.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; row_id: uuid; data: object	{ row }	not_found, validation_error

json

{
  "name": "update_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

delete_micro_db_row

Delete one row from a writable Micro DB table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; row_id: uuid	{ ok: true }	not_found, permission_denied

json

{
  "name": "delete_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

snapshot_micro_db

Serialize the full Micro DB into a workspace part version and prune free-tier retention.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ snapshot }	not_found, permission_denied

json

{
  "name": "snapshot_micro_db",
  "arguments": {
    "bucket": "..."
  }
}

Sources

list_sources

List non-archived sources attached to a readable workspace.

Auth	Parameters	Returns	Errors
read token	deprecated workspace slug alias?: string; owner_username?: string	{ workspace, sources }	not_found, unauthorized

json

{
  "name": "list_sources",
  "arguments": {
    "deprecated workspace slug alias": "..."
  }
}

read_source

Read the full extracted text of a non-archived source attached to a readable workspace.

Auth	Parameters	Returns	Errors
read token	deprecated workspace slug alias?: string; source_id: string; owner_username?: string	{ workspace, source }	not_found, unauthorized

json

{
  "name": "read_source",
  "arguments": {
    "deprecated workspace slug alias": "..."
  }
}

Sharing

add_grant

Grant view or write access to a collaborator for a whole workspace or one specific part.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; collaborator_user_id: uuid; level: 'view' \| 'write'; scope?: 'bucket' \| 'part'; part_slug?: string; part_type?: 'web_page' \| 'markdown_file'	{ grant }	not_found, permission_denied, validation_error

json

{
  "name": "add_grant",
  "arguments": {
    "bucket": "..."
  }
}

remove_grant

Remove a collaborator grant from a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; grant_id: uuid	{ ok: true }	not_found, permission_denied

json

{
  "name": "remove_grant",
  "arguments": {
    "bucket": "..."
  }
}

list_grants

List collaborator grants on a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ grants: Grant[] }	not_found, permission_denied

json

{
  "name": "list_grants",
  "arguments": {
    "bucket": "..."
  }
}

create_share_link

Create a share link for a workspace with optional expiry and optional Pro password protection.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; expires_at?: datetime \| null; password?: string \| null	{ share_link }	tier_limit_exceeded, permission_denied, validation_error

json

{
  "name": "create_share_link",
  "arguments": {
    "bucket": "..."
  }
}

revoke_share_link

Revoke an active workspace share link.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; share_link_id: uuid	{ share_link }	not_found, permission_denied

json

{
  "name": "revoke_share_link",
  "arguments": {
    "bucket": "..."
  }
}

list_share_links

List share links on a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ share_links: ShareLink[] }	not_found, permission_denied

json

{
  "name": "list_share_links",
  "arguments": {
    "bucket": "..."
  }
}

Images

push_image

Upload a JPEG, PNG, or WebP image to a writable workspace. The returned MiraDock image URL can be referenced from later Markdown pushes.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace id/path fields?: uuid\|string; image_base64: string <= 15 MB; filename: string; alt_text: string; caption?: string \| null; format_hint?: 'jpeg' \| 'jpg' \| 'png' \| 'webp' \| null	{ workspace_id, image_id, public_url, url, storage_path, format, width, height, markdown }	validation_error, tier_limit_exceeded, permission_denied

json

{
  "name": "push_image",
  "arguments": {
    "legacy workspace id/path fields": "..."
  }
}

Common errors

Code	Meaning
unauthorized	Missing, invalid, revoked, or expired bearer token.
permission_denied	Token is read-only, OAuth lacks mcp:write, or user cannot write the target.
forbidden	HTTPS is required for production MCP connections.
not_found	The workspace, page, source, table, row, grant, or version was not found.
bad_request	Required disambiguating fields were omitted.
validation_error	Zod or domain validation rejected the tool input.
tier_limit_exceeded	Plan limits block the requested write.
rate_limited	Request or write quotas were exceeded.
internal	Unhandled server error.

MCP JSON-RPC errors are returned with these code strings. Missing or invalid bearer values use HTTP 401 with WWW-Authenticate. Rate limits inside JSON-RPC use code rate_limited and may include retry_after_seconds.

Reference

MCP tools

Every tool the MiraDock MCP server exposes - what they do, how to call them, and what they return.

Overview

MCP clients call these tools through POST /mcp. The server registers the tools in lib/mcp/server.ts. Use the connect guides to wire a client.

Authentication

Tool reference

Workspaces

search_buckets

Search across workspaces that this MCP connection can read. Anonymous clients see public workspaces only; authenticated clients also see the token owner's private workspaces.

Auth	Parameters	Returns	Errors
read token	query: string; limit?: integer <= 50	JSON workspace list	unauthorized, rate_limited, internal

json

{
  "name": "search_buckets",
  "arguments": {
    "query": "..."
  }
}

list_buckets

List workspaces available to the client. Use visibility='public' for public-only results, 'private' for authenticated owner-private workspaces, or 'all' for everything readable.

Auth	Parameters	Returns	Errors
read token	visibility?: 'public' \| 'private' \| 'all'; owned_by_me?: boolean	JSON workspace list	unauthorized, rate_limited, internal

json

{
  "name": "list_buckets",
  "arguments": {
    "visibility": "..."
  }
}

get_bucket

Return metadata, owner identity, page/source counts, recent activity, page_kind_breakdown, top_entities, and top_concepts for a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket?: string; deprecated workspace slug alias?: string; owner_username?: string	Workspace metadata	bad_request, not_found, unauthorized, rate_limited

json

{
  "name": "get_bucket",
  "arguments": {
    "bucket": "..."
  }
}

create_bucket

Create a new private or public workspace owned by the write-token user. Add pages with push_web_page, push_markdown_file, or push_markdown.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	title?: string; name?: string; slug?: string; visibility?: 'private' \| 'public'; discoverable?: boolean; description?: string; tags?: string[]; topic_tag_slugs?: string[]	Created workspace	validation_error, tier_limit_exceeded, unauthorized, permission_denied, rate_limited

json

{
  "name": "create_bucket",
  "arguments": {
    "title": "..."
  }
}

fork_bucket

Create a private or public copy of a public workspace that allows forks. The fork keeps upstream attribution and tracking.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace path: owner_username/workspace_slug; new_name?: string \| null; visibility?: 'private' \| 'public'	Forked workspace metadata	not_found, forbidden, validation_error, unauthorized, permission_denied

json

{
  "name": "fork_bucket",
  "arguments": {
    "legacy workspace path": "..."
  }
}

update_bucket_metadata

Owner-only workspace metadata update for name, description, visibility, discoverability, and topic tags.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace path: owner_username/workspace_slug; name?: string; description?: string \| null; visibility?: 'private' \| 'public'; discoverable?: boolean; add_topics?: string[]; remove_topics?: string[]	Updated workspace metadata	not_found, permission_denied, validation_error

json

{
  "name": "update_bucket_metadata",
  "arguments": {
    "legacy workspace path": "..."
  }
}

list_my_buckets

List workspaces the write-token user can push to, including owned workspaces and Editor collaborations.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	include collaborations?: boolean; visibility?: 'private' \| 'public'; tag?: string	Writable workspace list	unauthorized, permission_denied, rate_limited

json

{
  "name": "list_my_buckets",
  "arguments": {
    "include collaborations": "..."
  }
}

update_bucket

Update workspace title, description, visibility, or tags.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; title?: string; description?: string \| null; visibility?: 'private' \| 'public'; tags?: string[]	{ bucket }	not_found, permission_denied, validation_error

json

{
  "name": "update_bucket",
  "arguments": {
    "bucket": "..."
  }
}

delete_bucket

Delete a workspace owned by the write-token user.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ ok: true }	not_found, permission_denied

json

{
  "name": "delete_bucket",
  "arguments": {
    "bucket": "..."
  }
}

set_cover_web_page

Set the cover Web page for a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; web_page: string	{ bucket }	not_found, permission_denied

json

{
  "name": "set_cover_web_page",
  "arguments": {
    "bucket": "..."
  }
}

set_grounding_bucket

Set a session-scoped active workspace for later get_web_page and list_web_pages calls that omit a workspace target.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace path: owner_username/workspace_slug	{ activeWorkspacePath }	not_found, unauthorized, permission_denied

json

{
  "name": "set_grounding_bucket",
  "arguments": {
    "legacy workspace path": "..."
  }
}

Web pages

list_web_pages

List page titles, slugs, summaries, content_type, page_kind values, last_updated timestamps, and claim_count values in a readable workspace. Use sort='alphabetical' when an agent needs deterministic navigation.

Auth	Parameters	Returns	Errors
read token	bucket?: string; deprecated workspace slug alias?: string; owner_username?: string; limit?: integer <= 100; sort?: 'alphabetical' \| 'recent'	Workspace page list	not_found, unauthorized, rate_limited

json

{
  "name": "list_web_pages",
  "arguments": {
    "bucket": "..."
  }
}

get_web_page

Read a workspace page with content_type plus structured grounding fields. HTML pages return sanitized HTML in native mode or extracted text in text mode.

Auth	Parameters	Returns	Errors
read token	bucket?: string; web_page?: string; deprecated workspace slug alias?: string; page_slug?: string; format?: 'native' \| 'text'; owner_username?: string	Workspace page content	bad_request, not_found, unauthorized

json

{
  "name": "get_web_page",
  "arguments": {
    "bucket": "..."
  }
}

search_web_pages

Search page titles, summaries, and text-readable page content across readable workspaces.

Auth	Parameters	Returns	Errors
read token	query: string; deprecated workspace slug alias?: string; owner_username?: string; limit?: integer <= 50	{ pages: McpPageSearchResult[] }	unauthorized, rate_limited

json

{
  "name": "search_web_pages",
  "arguments": {
    "query": "..."
  }
}

get_web_page_links

Return a page's outbound [[Page]] links and inbound backlinks so agents can walk the workspace graph.

Auth	Parameters	Returns	Errors
read token	deprecated workspace slug alias?: string; page_slug: string; owner_username?: string	{ outbound, inbound }	not_found, unauthorized

json

{
  "name": "get_web_page_links",
  "arguments": {
    "deprecated workspace slug alias": "..."
  }
}

push_web_page

Create or update one HTML Web page. Raw HTML is sanitized server-side before storage. Omit a workspace target to save into the token owner's default workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy workspace id/path fields?: uuid\|string; content_type?: 'markdown' \| 'html'; page_title?: string \| null; page_slug?: string \| null; page_content: string <= 1 MiB	{ part, action, warnings, sanitization_warnings? }	validation_error, tier_limit_exceeded, unauthorized, permission_denied, rate_limited

json

{
  "name": "push_web_page",
  "arguments": {
    "bucket": "..."
  }
}

delete_web_page

Delete a page from a workspace the write-token user owns or edits.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; web_page?: string; legacy workspace path?: string; page_slug?: string	{ ok: true }	bad_request, not_found, permission_denied

json

{
  "name": "delete_web_page",
  "arguments": {
    "bucket": "..."
  }
}

list_web_page_versions

List saved versions for a Web page.

Auth	Parameters	Returns	Errors
read token	bucket: string; web_page: string	{ versions: PartVersion[] }	not_found, unauthorized

json

{
  "name": "list_web_page_versions",
  "arguments": {
    "bucket": "..."
  }
}

get_web_page_version

Read a specific saved Web page version.

Auth	Parameters	Returns	Errors
read token	bucket: string; web_page: string; version: positive integer	{ version, content }	not_found, unauthorized

json

{
  "name": "get_web_page_version",
  "arguments": {
    "bucket": "..."
  }
}

restore_web_page_version

Restore a previous Web page version.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; web_page: string; version: positive integer	{ part }	not_found, permission_denied, validation_error

json

{
  "name": "restore_web_page_version",
  "arguments": {
    "bucket": "..."
  }
}

Artifacts (markdown files)

push_markdown_file

Create or update one Markdown file using a complete Markdown document with YAML front matter. Omit a workspace target to save into the token owner's default workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy workspace id/path fields?: uuid\|string; page_title?: string \| null; page_slug?: string \| null; page_content: string <= 1 MiB	{ part, action, warnings }	invalid_front_matter, invalid_slug, validation_error

json

{
  "name": "push_markdown_file",
  "arguments": {
    "bucket": "..."
  }
}

push_markdown

Create or update one Markdown artifact. Provide a workspace slug to save it in a workspace; omit it for standalone.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; page_title?: string \| null; page_slug?: string \| null; page_content: string <= 1 MiB	{ part, action, warnings }	invalid_front_matter, invalid_slug, validation_error

json

{
  "name": "push_markdown",
  "arguments": {
    "bucket": "..."
  }
}

get_markdown_file

Read one Markdown file from a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket: string; markdown_file: string	{ part }	not_found, unauthorized

json

{
  "name": "get_markdown_file",
  "arguments": {
    "bucket": "..."
  }
}

list_markdown_files

List Markdown files in a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket: string	{ parts: BucketPart[] }	not_found, unauthorized

json

{
  "name": "list_markdown_files",
  "arguments": {
    "bucket": "..."
  }
}

delete_markdown_file

Delete a Markdown file from a writable workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; markdown_file: string	{ ok: true }	not_found, permission_denied

json

{
  "name": "delete_markdown_file",
  "arguments": {
    "bucket": "..."
  }
}

list_markdown_file_versions

List saved versions for a Markdown file.

Auth	Parameters	Returns	Errors
read token	bucket: string; markdown_file: string	{ versions: PartVersion[] }	not_found, unauthorized

json

{
  "name": "list_markdown_file_versions",
  "arguments": {
    "bucket": "..."
  }
}

get_markdown_file_version

Read a specific saved Markdown file version.

Auth	Parameters	Returns	Errors
read token	bucket: string; markdown_file: string; version: positive integer	{ version, content }	not_found, unauthorized

json

{
  "name": "get_markdown_file_version",
  "arguments": {
    "bucket": "..."
  }
}

restore_markdown_file_version

Restore a previous Markdown file version.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; markdown_file: string; version: positive integer	{ part }	not_found, permission_denied

json

{
  "name": "restore_markdown_file_version",
  "arguments": {
    "bucket": "..."
  }
}

Micro DBs

push_micro_db

Create or update the Micro DB artifact shell.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; title?: string \| null; slug?: string \| null; visibility?: 'private' \| 'public'; summary?: string \| null	{ part }	validation_error, permission_denied

json

{
  "name": "push_micro_db",
  "arguments": {
    "bucket": "..."
  }
}

list_micro_db_tables

List tables in the micro-database attached to a readable workspace.

Auth	Parameters	Returns	Errors
read token	bucket: string	{ tables: MicroDbTable[] }	not_found, unauthorized

json

{
  "name": "list_micro_db_tables",
  "arguments": {
    "bucket": "..."
  }
}

get_micro_db_schema

Return one Micro DB table and its typed columns.

Auth	Parameters	Returns	Errors
read token	bucket: string; table: string	{ table, columns }	not_found, unauthorized

json

{
  "name": "get_micro_db_schema",
  "arguments": {
    "bucket": "..."
  }
}

query_micro_db_rows

Query rows with structured AND filters, validated column slugs, typed comparisons, sorting, limit, and offset.

Auth	Parameters	Returns	Errors
read token	bucket: string; table: string; filter?: MicroDbFilter[]; sort?: MicroDbSort[]; limit?: integer <= 500; offset?: integer >= 0	{ rows, total? }	not_found, validation_error

json

{
  "name": "query_micro_db_rows",
  "arguments": {
    "bucket": "..."
  }
}

get_micro_db_row

Read one row from a Micro DB table by id.

Auth	Parameters	Returns	Errors
read token	bucket: string; table: string; row_id: uuid	{ row }	not_found, unauthorized

json

{
  "name": "get_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

create_micro_db_table

Create a typed table in a writable Micro DB.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; name: string; slug?: string; description?: string \| null; columns: MicroDbColumnDef[]	{ table }	validation_error, permission_denied

json

{
  "name": "create_micro_db_table",
  "arguments": {
    "bucket": "..."
  }
}

update_micro_db_table

Update Micro DB table metadata.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; name?: string; description?: string \| null; position?: integer	{ table }	not_found, validation_error

json

{
  "name": "update_micro_db_table",
  "arguments": {
    "bucket": "..."
  }
}

delete_micro_db_table

Snapshot the Micro DB, then delete a table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string	{ ok: true, snapshot? }	not_found, permission_denied

json

{
  "name": "delete_micro_db_table",
  "arguments": {
    "bucket": "..."
  }
}

add_micro_db_column

Add a typed column to a Micro DB table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; column_def: MicroDbColumnDef	{ column }	validation_error, permission_denied

json

{
  "name": "add_micro_db_column",
  "arguments": {
    "bucket": "..."
  }
}

update_micro_db_column

Update a Micro DB column definition.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; column: string; patch: Partial<MicroDbColumnDef>	{ column }	not_found, validation_error

json

{
  "name": "update_micro_db_column",
  "arguments": {
    "bucket": "..."
  }
}

delete_micro_db_column

Snapshot the Micro DB, then delete a column definition.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; column: string	{ ok: true, snapshot? }	not_found, permission_denied

json

{
  "name": "delete_micro_db_column",
  "arguments": {
    "bucket": "..."
  }
}

insert_micro_db_row

Validate and insert one row into a Micro DB table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; data: object	{ row }	validation_error, permission_denied

json

{
  "name": "insert_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

insert_micro_db_rows

Validate and insert rows in one all-or-nothing bulk write.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; rows: object[]	{ rows }	validation_error, permission_denied

json

{
  "name": "insert_micro_db_rows",
  "arguments": {
    "bucket": "..."
  }
}

update_micro_db_row

Patch one Micro DB row; data keys merge into the existing JSON row.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; row_id: uuid; data: object	{ row }	not_found, validation_error

json

{
  "name": "update_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

delete_micro_db_row

Delete one row from a writable Micro DB table.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; table: string; row_id: uuid	{ ok: true }	not_found, permission_denied

json

{
  "name": "delete_micro_db_row",
  "arguments": {
    "bucket": "..."
  }
}

snapshot_micro_db

Serialize the full Micro DB into a workspace part version and prune free-tier retention.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ snapshot }	not_found, permission_denied

json

{
  "name": "snapshot_micro_db",
  "arguments": {
    "bucket": "..."
  }
}

Sources

list_sources

List non-archived sources attached to a readable workspace.

Auth	Parameters	Returns	Errors
read token	deprecated workspace slug alias?: string; owner_username?: string	{ workspace, sources }	not_found, unauthorized

json

{
  "name": "list_sources",
  "arguments": {
    "deprecated workspace slug alias": "..."
  }
}

read_source

Read the full extracted text of a non-archived source attached to a readable workspace.

Auth	Parameters	Returns	Errors
read token	deprecated workspace slug alias?: string; source_id: string; owner_username?: string	{ workspace, source }	not_found, unauthorized

json

{
  "name": "read_source",
  "arguments": {
    "deprecated workspace slug alias": "..."
  }
}

Sharing

add_grant

Grant view or write access to a collaborator for a whole workspace or one specific part.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; collaborator_user_id: uuid; level: 'view' \| 'write'; scope?: 'bucket' \| 'part'; part_slug?: string; part_type?: 'web_page' \| 'markdown_file'	{ grant }	not_found, permission_denied, validation_error

json

{
  "name": "add_grant",
  "arguments": {
    "bucket": "..."
  }
}

remove_grant

Remove a collaborator grant from a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; grant_id: uuid	{ ok: true }	not_found, permission_denied

json

{
  "name": "remove_grant",
  "arguments": {
    "bucket": "..."
  }
}

list_grants

List collaborator grants on a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ grants: Grant[] }	not_found, permission_denied

json

{
  "name": "list_grants",
  "arguments": {
    "bucket": "..."
  }
}

create_share_link

Create a share link for a workspace with optional expiry and optional Pro password protection.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; expires_at?: datetime \| null; password?: string \| null	{ share_link }	tier_limit_exceeded, permission_denied, validation_error

json

{
  "name": "create_share_link",
  "arguments": {
    "bucket": "..."
  }
}

revoke_share_link

Revoke an active workspace share link.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string; share_link_id: uuid	{ share_link }	not_found, permission_denied

json

{
  "name": "revoke_share_link",
  "arguments": {
    "bucket": "..."
  }
}

list_share_links

List share links on a workspace.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket: string	{ share_links: ShareLink[] }	not_found, permission_denied

json

{
  "name": "list_share_links",
  "arguments": {
    "bucket": "..."
  }
}

Images

push_image

Upload a JPEG, PNG, or WebP image to a writable workspace. The returned MiraDock image URL can be referenced from later Markdown pushes.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy workspace id/path fields?: uuid\|string; image_base64: string <= 15 MB; filename: string; alt_text: string; caption?: string \| null; format_hint?: 'jpeg' \| 'jpg' \| 'png' \| 'webp' \| null	{ workspace_id, image_id, public_url, url, storage_path, format, width, height, markdown }	validation_error, tier_limit_exceeded, permission_denied

json

{
  "name": "push_image",
  "arguments": {
    "legacy workspace id/path fields": "..."
  }
}

Common errors

Code	Meaning
unauthorized	Missing, invalid, revoked, or expired bearer token.
permission_denied	Token is read-only, OAuth lacks mcp:write, or user cannot write the target.
forbidden	HTTPS is required for production MCP connections.
not_found	The workspace, page, source, table, row, grant, or version was not found.
bad_request	Required disambiguating fields were omitted.
validation_error	Zod or domain validation rejected the tool input.
tier_limit_exceeded	Plan limits block the requested write.
rate_limited	Request or write quotas were exceeded.
internal	Unhandled server error.