MCP Tools Reference

These tools are available to your AI assistant once your MCP client is connected.

Document operations

docs_list

Lists all documents in a workspace or project. Returns titles, identifiers, and basic metadata. Filter by project to focus on a specific area.

Also answers “which documents have property X”: pass filters[] with exact predicates on built-in properties (name, workflow, updatedAt, parentId, …) or on Custom Fields as cf.KEY, plus an optional sort. server_info.filters lists every target with its valid operators. Custom-field predicates require a projectId. Archived documents are excluded unless you pass include_archived: true.

docs_get

Retrieves a document’s full content, including Markdown text and metadata. Identify documents by UUID, alias, or short code via the docId parameter (batch reads with docIds accept all three, mixed). The response includes a shortUrl field — the document’s app.meldoc.io/d/{code} link — alongside the canonical url.

A document’s short code works anywhere a UUID or alias is accepted: docs_get (including batch), docs_update, docs_delete, docs_related, docs_graph, and asset_attach. Resolution stays within your token’s workspace, and short codes aren’t supported inside [[wiki-link]] syntax — that stays on aliases.

docs_tree

Displays the hierarchical structure of documents in a project, showing parent-child relationships. Archiving Documents are hidden by default; pass include_archived: true to show them in place, marked with archived: true.

docs_search

Hybrid search (semantic + full-text) across all documents. Returns ranked results with context showing where matches were found. Set include_content: true to receive the first N characters inline — useful when you want content without a separate docs_get call. Falls back to full-text search when AI search is unavailable. After a strong hit, pair with docs_related to catch adjacent documents that search missed.

A query that is a document’s exact alias — current or Renaming & Redirects — resolves to that document directly, before full-text ranking. Archived documents are excluded unless you pass include_archived: true.

docs_audit

Runs a project-wide quality check. Use it for a deliberate cleanup pass — for everyday work, duplicates already surface inside docs_search results. Pass a kind:

• duplicates — clusters of near-identical documents.
• broken_links — documents whose [[...]] links don’t resolve, worst offenders first.
• stale_aliases — links that still use a Renaming & Redirects of their target, grouped by the retired name; entries with redirectExists: false are urgent, because the next edit of the referring document breaks them.
• search_gaps — searches that repeatedly came back empty, ranked by how often — the holes in your knowledge base.

Every kind requires a projectId except stale_aliases, which can run workspace-wide — omit projectId to see the damage a project rename does across other projects.

docs_create

Creates a new document. Specify title, content in Markdown, and optionally set hierarchy position. A leading # H1 line in the content is moved into the title field — don’t re-emit it when round-tripping.

Returns {id, alias, title, createdAt}. Write responses omit _meta — server_info is the canonical place for scope.

Requires write permissions.

docs_update

Updates a document’s content, title, or metadata. Supports two modes:

Full content replace — pass contentMd to overwrite the document. A leading # H1 line is moved into title and won’t appear in stored content.

Partial edits (preferred for small changes) — pass sections[] and/or replacements[] instead of contentMd. Saves tokens and reduces the risk of agents mutating unrelated content.

Section modes

mode	Required fields	Effect
replace	headingPath (or target), content	Replace section body (heading preserved). content is body without the heading line.
delete	headingPath (or target)	Remove heading + body, including nested subsections.
insertAtStart	content	Insert at the top, after frontmatter.
insertAtEnd	content	Append at the bottom.
insertBefore	anchor (or target), content	Insert before the anchor heading.
insertAfter	anchor (or target), content	Insert after the anchor section’s full subtree.

The target field works for all section-targeting modes. Sending both target and headingPath/anchor returns patch_invalid_combination.

Heading paths

headingPath and anchor are full paths from the document root, level by level. A ### OAuth Flow nested under ## Authentication under # API is ["API", "Authentication", "OAuth Flow"] — not just ["OAuth Flow"]. Use docs_get(headings_only: true) to read the outline first.

Anchors resolve against the original content. Patches don’t see each other’s effects within a single call. If any anchor is missing or two ranges overlap, the document stays untouched.

Replacements

replacements[] run after sections[], against the post-section content. If a section is replaced or deleted in the same call, a find targeting the old text will fail. Write replacements against the new content, or split into two calls.

Recommended authoring loop

1. docs_get(docId, headings_only: true) → see structure
2. Identify what to change locally
3. docs_update(
     docId,
     sections=[{mode: "replace", headingPath: ["Auth"], content: "..."}],
     replacements=[{find: "OldName", replace: "NewName"}],
     expectedUpdatedAt=<from get>)
4. Verify via the agentHint field on the response.

Concurrency and preview

expectedUpdatedAt provides optimistic concurrency. Concurrent edits return a conflict error with the actual currentUpdatedAt, so the agent can re-fetch and retry without a second round-trip.

dryRun: true with returnOutline: true or returnContent: true shows what a patch would produce without mutating the document.

returnOutline (cheap) or returnContent (verbose) returns post-update state in the same response, skipping a verification round-trip.

Every error carries a Hint: suffix with the recovery action — docs_get(headings_only:true) for section_not_found, “extend find with surrounding context” for replacement_ambiguous, etc.

Prefer partial patches over rewriting contentMd for small changes.

Capability discovery: server_info.writeOps advertises fullReplace, sectionPatch, sectionInsert, textReplace flags so older deployments without partial mode can be detected.

Archiving

docs_update is also how an assistant Archiving Documents a document: archived: true retires it (and its whole subtree), archived: false revives it. An archived document is read-only, so to edit a retired page, send archived: false together with the edits in one call. replacedBy (alias or id of a live document in the same project) records what supersedes it.

Requires write permissions.

docs_delete

Soft-deletes a document. It disappears from listings, search, and embeddings but stays in the database — workspace admins can restore it via the web UI. Children are soft-deleted as a unit. Aliases stay reserved.

Deleting by a Renaming & Redirects is refused — the name now points somewhere else, and the error names the current alias so the call can be retried safely.

This is not a hard delete. For permanent removal, use workspace admin tools. Requires a token with the Write and Delete permission level.

Note: Write operations (docs_create, docs_update, docs_delete) require the Pro plan or higher.

docs_related

Shows how a document connects to the rest of your workspace. Best used after docs_search to expand context — catches docs that search missed because they’re structurally connected rather than lexically similar.

Pass a view to choose the projection:

• No view — full neighborhood: outgoing links, backlinks, parent + children, and semantic neighbors.
• view: "outgoing" — only outgoing [[wiki-links]]. See what a doc references.
• view: "incoming" — only backlinks. See who depends on a doc before changing it.
• view: "suggest-links" — semantic candidates not yet linked. Surface docs you might want to reference.

Recommended flow: docs_search(query) → top hit → docs_related(docId) → docs_get(alias).

docs_graph

Returns a structural map of how documents connect through [[wiki-links]] and parent-child hierarchy. Pass a docId for the subgraph around one document, a projectId for a whole-project map, or no arguments for a workspace overview. Use it after docs_search when you need the shape of an area, not to find documents by topic.

docs_history

Reads a document’s Version History. Meldoc groups edits into sessions, so a version is the result of a session rather than of one save.

Pass a view to choose the projection:

• view: "list" — the versions themselves: number, when, who, which channel, and how many saves each absorbed.
• view: "content" — one version’s content and custom field values, chosen with revision.
• view: "diff" — what changed between two points, as a unified diff. Compares against the live document by default.

docs_update also accepts returnDiff: true, which returns the diff of the edit you just made — the cheapest way to report your own changes back to a human.

This tool is read-only, and restoring a version is not available over MCP by design: replacing a document with an older one is a decision for a person looking at the diff. An agent can still read a version with view: "content" and write it back with docs_update — deliberately, and recorded like any other edit.

Asset operations

assets_list

Lists assets in your workspace with metadata (name, type, size, SHA256). Use query to filter by file name.

asset_get

Gets asset metadata and usage details, including which documents use it. For text files under 50 KB, also returns content. Accepts UUID or SHA256.

asset_attach

Attaches an existing asset to a document. Optionally inserts Markdown image/link syntax into the content. Requires write permissions.

Project operations

projects_list

Lists all projects in your workspace with names, identifiers, access levels, and your effective permissions on each.

projects_create

Creates a new project. Pass a name; the alias is derived from it (or pass your own). Any workspace member can create projects, and the authorizing user becomes the project’s admin. OAuth sessions only — integration tokens can’t create projects.

project_contributors_list

Lists a project’s Project Collaborators with their roles. Call it before adding someone, to see who already has access.

project_contributors_add

Adds an existing workspace member to a project by email, with a role: write, maintain, or admin. The person must already belong to the workspace — this tool never sends invitations. Requires project admin rights.

Comment operations

Read and answer Document Workflow — useful when an assistant works through review feedback. All comment tools require an OAuth session (integration tokens can’t comment).

comments_list

Lists a document’s comment threads — each with its status, quoted text (for inline threads), authors, and the comments themselves. Filter with status: open (default), resolved, or all.

comments_create

Starts a new document-level comment thread. Assistants always comment on the document as a whole — anchoring a comment to a text span stays a human action in the editor.

comments_reply

Appends a reply to an existing thread. Replying to a resolved thread is allowed and does not reopen it.

comments_resolve / comments_reopen

Mark a thread resolved, or reopen it. Both are idempotent.

comments_update

Edits a comment’s body — only the comment’s own author can edit it.

Custom field operations

Manage a project’s Custom Fields and their values on documents.

fields_list

Lists a project’s field definitions in display order.

fields_define

Adds a field to a project: label, type (string | number | boolean | list | select), options for selects, and an optional defaultValue. The stable key is derived from the label. Requires write permissions.

fields_update

Updates a field’s label, order, options, or default. When renaming a select option, pass optionRenames: [{from, to}] so documents holding the old value migrate to the new one — a plain options replacement would strand them. Passing defaultValue: null removes the default and pins the outgoing value onto every document that was inheriting it. Requires write permissions.

fields_delete

Deletes a field definition and every stored value of it across documents. Requires write permissions.

doc_fields_set

Sets a field’s value on one document. Three intents: pass a typed value to set it, pass value: null to store an explicitly empty value (it overrides the project default), or omit value entirely to reset the document to the default. Requires write permissions.

Glossary operations

glossary_list

Lists glossary terms. Supports search to filter, limit to cap results, and brief for compact output.

glossary_get

Fetches a term by name. Pass a single term or a terms array to fetch up to 10 at once. Missing terms are silently skipped.

glossary_add

Creates a new term. Pass a single term and definition, or an items array to create up to 10 in one call.

glossary_update

Updates an existing term — definition, aliases, or case sensitivity. Pass a single term or an items array.

glossary_delete

Removes a term. Pass a single term or a terms array to delete up to 10 at once.

Note: Glossary write operations require a write token with Glossary Write also enabled. Read operations work with any authenticated session. See Integration Tokens for token scoping.

Management operations

server_info

Shows account information, permissions, server capabilities, and the app URL contract (app.baseUrl + app.linkTemplates) so your assistant can build links to workspaces, projects, and documents without a separate tool call. The identifiers needed to fill the templates (workspace slug, project ID, doc ID) come from the same MCP responses your assistant already uses — docs_get, docs_list, docs_search, projects_list. Single-doc docs_get responses also include pre-built url and shortUrl fields for convenience — share the shortUrl when you want a short, stable link that survives moves.

list_workspaces

Lists all workspaces you have access to, including names, aliases, and your access level.

get_workspace

Shows which workspace is currently active. There is no tool that sets it — when your token reaches more than one workspace, pass workspaceAlias on the call itself, or pin one in the connector configuration. See Workspace Management.

auth_login_instructions

Returns step-by-step instructions for authenticating with Meldoc. Covers OAuth, token, and device flow. Available without a token.

Document types

templates_list

Lists the project’s document types — alias, title, description, icon, and the ordered set of custom fields each one carries.

templates_get

One type in full. The field order in the response is the order the type arranges its fields in; position 0 renders first.

Natural language examples

Ask naturally — your assistant picks the right tool:

“Show me all documents in the API project” “Find information about authentication” “What’s connected to the api-authentication doc?” “Create a new document about our deployment process” “Which documents link to the database schema?” “Suggest related docs I should link from this page”

What’s next?

Getting Started with MCP — Initial setup.

Authentication — Authentication methods.

Workspace Management — Workspace management.