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

Docks

search_buckets

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

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

json

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

list_buckets

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

Auth	Parameters	Returns	Errors
read token	visibility?: 'public' \| 'private' \| 'all'; owned_by_me?: boolean	JSON Dock 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 Dock.

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

json

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

create_bucket

Create a new private or public Dock 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 Dock	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 Dock that allows forks. The fork keeps upstream attribution and tracking.

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

json

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

update_bucket_metadata

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

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

json

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

list_my_buckets

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

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

json

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

update_bucket

Update Dock 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 Dock 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 Dock.

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 Dock for later get_web_page and list_web_pages calls that omit a Dock target.

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

json

{
  "name": "set_grounding_bucket",
  "arguments": {
    "legacy Dock 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 Dock. Use sort='alphabetical' when an agent needs deterministic navigation.

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

json

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

get_web_page

Read a Dock 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 Dock slug alias?: string; page_slug?: string; format?: 'native' \| 'text'; owner_username?: string	Dock 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 Docks.

Auth	Parameters	Returns	Errors
read token	query: string; deprecated Dock 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 Dock graph.

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

json

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

push_web_page

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

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy Dock 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 Dock the write-token user owns or edits.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; web_page?: string; legacy Dock 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 Dock target to save into the token owner's default Dock.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy Dock 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 Dock slug to save it in a Dock; 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 Dock.

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 Dock.

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 Dock.

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 Dock.

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 Dock 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 Dock.

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

json

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

read_source

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

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

json

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

Sharing

add_grant

Grant view or write access to a collaborator for a whole Dock 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 Dock.

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 Dock.

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 Dock 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 Dock 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 Dock.

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 Dock. The returned MiraDock image URL can be referenced from later Markdown pushes.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy Dock 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 Dock 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 Dock, 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

Docks

search_buckets

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

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

json

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

list_buckets

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

Auth	Parameters	Returns	Errors
read token	visibility?: 'public' \| 'private' \| 'all'; owned_by_me?: boolean	JSON Dock 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 Dock.

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

json

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

create_bucket

Create a new private or public Dock 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 Dock	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 Dock that allows forks. The fork keeps upstream attribution and tracking.

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

json

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

update_bucket_metadata

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

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

json

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

list_my_buckets

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

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

json

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

update_bucket

Update Dock 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 Dock 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 Dock.

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 Dock for later get_web_page and list_web_pages calls that omit a Dock target.

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

json

{
  "name": "set_grounding_bucket",
  "arguments": {
    "legacy Dock 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 Dock. Use sort='alphabetical' when an agent needs deterministic navigation.

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

json

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

get_web_page

Read a Dock 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 Dock slug alias?: string; page_slug?: string; format?: 'native' \| 'text'; owner_username?: string	Dock 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 Docks.

Auth	Parameters	Returns	Errors
read token	query: string; deprecated Dock 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 Dock graph.

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

json

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

push_web_page

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

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy Dock 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 Dock the write-token user owns or edits.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; web_page?: string; legacy Dock 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 Dock target to save into the token owner's default Dock.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	bucket?: string; legacy Dock 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 Dock slug to save it in a Dock; 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 Dock.

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 Dock.

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 Dock.

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 Dock.

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 Dock 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 Dock.

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

json

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

read_source

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

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

json

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

Sharing

add_grant

Grant view or write access to a collaborator for a whole Dock 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 Dock.

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 Dock.

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 Dock 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 Dock 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 Dock.

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 Dock. The returned MiraDock image URL can be referenced from later Markdown pushes.

Auth	Parameters	Returns	Errors
write token or OAuth mcp:write	legacy Dock 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 Dock 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 Dock, 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.