<!-- Generated by scripts/gen-mcp-tool-docs.js from mcp/tools/*.js. Do not edit by hand: run npm run docs:mcp. -->

MCP tool reference

The DocSpace MCP server (docspace 0.4.0) exposes 33 tools, listed below in the order tools/list returns them. Each tool needs one scope on the agent key and a key role at least as high as the scope's minimum role (custom roles need the listed permission instead). See Scopes and roles for how the check works and Errors for what a denied call returns.

Behaviour comes from the tool annotations: read-only tools never write; additive writes only create data; overwrites may replace existing data.

Summary

get_context

Get cited context pack · scope pages:read · minimum role viewer · custom-role permission CONTENT_READ · read-only

Returns one compact, cited markdown context pack for a query, a page or a work item: ranked page excerpts (FTS + embeddings), one-hop linked pages, page owners and open work items, within budget_tokens. Citations: [page:<id>], [block:<id>], [work_item:<id>]. truncated=true when content was dropped to fit. Use it first to answer a question from the space, and cite the returned ids in the answer.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "query": {
      "description": "free-text question or topic",
      "type": "string",
      "maxLength": 500
    },
    "page_id": {
      "description": "anchor page id",
      "type": "integer"
    },
    "work_item_id": {
      "description": "anchor work item id (needs planner:read)",
      "type": "integer"
    },
    "budget_tokens": {
      "description": "token budget for the markdown (default 4000)",
      "type": "integer",
      "minimum": 200,
      "maximum": 32000
    }
  }
}

search

Search pages · scope pages:read · minimum role viewer · custom-role permission CONTENT_READ · read-only

Full-text search over page titles and block content in the space. Returns matching pages and blocks with their ids. Use it to locate pages by keyword; use get_context for a ranked, cited answer pack.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string"
    }
  },
  "required": [
    "q"
  ]
}

get_mentions

Count term mentions · scope pages:read · minimum role viewer · custom-role permission CONTENT_READ · read-only

Counts whole-word, case-insensitive mentions of a term in permitted pages and board items. Returns the total, per-page and per-board counts, monthly counts and top co-occurring terms. Use it to answer how often or where a term is mentioned.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "term": {
      "type": "string",
      "minLength": 2,
      "maxLength": 64,
      "description": "Word or phrase to count"
    },
    "from": {
      "description": "ISO date, start of the monthly chart window",
      "type": "string"
    },
    "to": {
      "description": "ISO date, end of the monthly chart window (default: now)",
      "type": "string"
    }
  },
  "required": [
    "term"
  ]
}

list_pages

List pages · scope pages:read · minimum role viewer · custom-role permission CONTENT_READ · read-only

Returns every page in the space as a flat list (id, title, icon, parent_id, position) that forms the page tree. Use it to browse the structure or find a page id by title; use search for content.

Parameters: none.

Input schema:

{
  "type": "object",
  "properties": {}
}

get_page

Get page · scope pages:read · minimum role viewer · custom-role permission CONTENT_READ · read-only

Returns one page with its ordered blocks and its backlinks (pages that link to it). Use it to read a page in full after search, list_pages or get_context gave you its id.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "page id"
    }
  },
  "required": [
    "id"
  ]
}

get_backlinks

Get page backlinks · scope pages:read · minimum role viewer · custom-role permission CONTENT_READ · read-only

Returns the pages that link to the given page through [[wiki-links]], with a snippet of each link. Use it to see where a page is referenced.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    }
  },
  "required": [
    "id"
  ]
}

get_graph

Get knowledge graph · scope pages:read · minimum role viewer · custom-role permission CONTENT_READ · read-only

Returns the knowledge graph of the space: nodes (pages) and edges (resolved [[wiki-links]]). Use it to map how pages connect; it can be large, so prefer get_backlinks for one page.

Parameters: none.

Input schema:

{
  "type": "object",
  "properties": {}
}

create_page

Create page · scope pages:write · minimum role editor · custom-role permission CONTENT_WRITE · write (additive)

Creates a page in the space and returns it (id, title, parent_id). Use it only when the user asks to create a page; add content afterwards with append_block. parent_id nests it under an existing page.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "icon": {
      "type": "string"
    },
    "parent_id": {
      "type": [
        "number",
        "null"
      ]
    }
  }
}

append_block

Append block to page · scope pages:write · minimum role editor · custom-role permission CONTENT_WRITE · write (additive)

Appends one block (paragraph, heading, todo, bullet, quote or code) to the end of a page and returns the new block. Write [[Page title]] in content to link another page. Use it to add content the user asked for; it never edits existing blocks.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "number"
    },
    "type": {
      "type": "string",
      "enum": [
        "paragraph",
        "heading",
        "todo",
        "bullet",
        "quote",
        "code"
      ]
    },
    "content": {
      "type": "string"
    },
    "checked": {
      "type": "boolean"
    }
  },
  "required": [
    "page_id"
  ]
}

list_boards

List boards · scope boards:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns the boards in the space (id, title, icon, type). Use it to find a board id before get_board or add_row.

Parameters: none.

Input schema:

{
  "type": "object",
  "properties": {}
}

get_board

Get board · scope boards:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns one board with its columns, rows, cell values and automations. Use it to read tabular data or to find column and row ids before add_row or set_cell.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    }
  },
  "required": [
    "id"
  ]
}

create_board

Create board · scope boards:write · minimum role editor · custom-role permission BOARDS_WRITE · write (additive)

Creates a board with the default columns (Task, Status, Owner, Date) and returns it. Use it only when the user asks for a new board.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "icon": {
      "type": "string"
    }
  }
}

add_row

Add board row · scope boards:write · minimum role editor · custom-role permission BOARDS_WRITE · write (additive)

Adds a row to a board and returns { row_id }. values maps column id to cell value ({ "12": "Done" }); get column ids from get_board.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "board_id": {
      "type": "number"
    },
    "values": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "required": [
    "board_id"
  ]
}

set_cell

Set board cell · scope boards:write · minimum role editor · custom-role permission BOARDS_WRITE · write (overwrites existing data)

Overwrites one cell (row_id, column_id) with value and returns the result. Matching board automations run after the write. Use it when the user asks to change a value.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "row_id": {
      "type": "number"
    },
    "column_id": {
      "type": "number"
    },
    "value": {
      "type": "string"
    }
  },
  "required": [
    "row_id",
    "column_id",
    "value"
  ]
}

create_automation

Create board automation · scope boards:write · minimum role editor · custom-role permission BOARDS_WRITE · write (additive)

Creates a board automation: when trigger_column is set to trigger_value, set action_column to action_value (set_cell) or notify. Returns the automation. Use it only when the user asks for an automation.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "board_id": {
      "type": "number"
    },
    "name": {
      "type": "string"
    },
    "trigger_column": {
      "type": "number"
    },
    "trigger_value": {
      "type": "string"
    },
    "action_type": {
      "type": "string",
      "enum": [
        "set_cell",
        "notify"
      ]
    },
    "action_column": {
      "type": "number"
    },
    "action_value": {
      "type": "string"
    }
  },
  "required": [
    "board_id",
    "trigger_column",
    "trigger_value"
  ]
}

list_services

List catalog services · scope catalog:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns every service registered in the space's catalog boards (row id, name, owner, tier, repo, on-call, status). Use it to find a service before get_service or get_scorecard.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "space_id": {
      "description": "space id; defaults to the connection's space",
      "type": "number"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  }
}

get_service

Get catalog service · scope catalog:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns one catalog service (a catalog board row) with all its cells and its linked page. Use it for the details of a service found with list_services.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "row_id": {
      "type": "number",
      "description": "service row id"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "row_id"
  ]
}

create_service

Create catalog service · scope catalog:write · minimum role editor · custom-role permission BOARDS_WRITE · write (additive)

Adds a service to a catalog board (type=catalog) and returns { row_id }. Use it only when the user asks to register a service.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "board_id": {
      "type": "number",
      "description": "id of a catalog board"
    },
    "name": {
      "type": "string",
      "description": "service name (Service column)"
    },
    "owner": {
      "description": "service owner",
      "type": "string"
    },
    "tier": {
      "description": "tier: P0/P1/P2/P3",
      "type": "string"
    },
    "repo": {
      "description": "service repository",
      "type": "string"
    },
    "on_call": {
      "description": "on-call person",
      "type": "string"
    },
    "status": {
      "description": "status: Active/Experimental/Deprecated",
      "type": "string"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "board_id",
    "name"
  ]
}

update_service

Update catalog service · scope catalog:write · minimum role editor · custom-role permission BOARDS_WRITE · write (overwrites existing data)

Overwrites cells of a catalog service by column name (case-insensitive) and returns { row_id, updated } with the columns written. Unknown column names are skipped.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "row_id": {
      "type": "number",
      "description": "service row id"
    },
    "fields": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "type": "string"
      },
      "description": "map of column name to new value"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "row_id",
    "fields"
  ]
}

list_scorecards

List scorecards · scope scorecards:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns the scorecards (rules and weights) defined for a catalog board. Use it to see how services are graded.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "board_id": {
      "type": "number",
      "description": "id of a catalog board"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "board_id"
  ]
}

get_scorecard

Get scorecard result · scope scorecards:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns the scorecard result for one catalog service row: overall score and a per-rule breakdown. Use it to check a service's maturity or compliance.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "row_id": {
      "type": "number",
      "description": "row id in a catalog board"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "row_id"
  ]
}

get_ownership_graph

Get ownership graph · scope catalog:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns the ownership graph of the space: pages, catalog services and the ownership edges between them. Use it to answer who owns a service or which docs describe it.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "space_id": {
      "description": "space id; defaults to the connection's space",
      "type": "number"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  }
}

sync_from_github

Sync page from GitHub · scope sync:write · minimum role editor · custom-role permission CONTENT_WRITE · write (overwrites existing data), reaches the internet

Fetches a Markdown file from a GitHub repository and syncs it into a DocSpace page now, overwriting the synced page content (or flagging a conflict). Returns the sync result. Reaches github.com; use it only when the user asks to sync that file.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "description": "GitHub repository as \"owner/repo\""
    },
    "path": {
      "type": "string",
      "description": "file path inside the repository, e.g. \"docs/README.md\""
    },
    "space_id": {
      "description": "space id; defaults to the connection's space",
      "type": "number"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "repo",
    "path"
  ]
}

list_work_items

List work items · scope planner:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns the work items of a space, filtered by sprint, status, assignee, type or title text. Use it to answer what is planned, in progress or assigned to someone.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "space_id": {
      "type": "number",
      "description": "space id"
    },
    "sprint_id": {
      "description": "sprint id filter (null = backlog)",
      "type": [
        "number",
        "null"
      ]
    },
    "status": {
      "description": "backlog | todo | in_progress | in_review | done | cancelled",
      "type": "string"
    },
    "assignee_id": {
      "description": "assignee user id",
      "type": "string"
    },
    "type": {
      "description": "epic | story | task | subtask | bug",
      "type": "string"
    },
    "text": {
      "description": "partial, case-insensitive match on the title",
      "type": "string"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "space_id"
  ]
}

get_work_item

Get work item · scope planner:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns one work item with its fields, links and linked git refs (branches, commits, PRs). Use it for the details of an item found with list_work_items.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "work item id"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

get_item_git_refs

Get git refs for item · scope planner:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns the git refs (branches, commits, pull requests) linked to a work item or page through smart commits or webhooks.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "work item or page id"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

list_sprints

List sprints · scope planner:read · minimum role viewer · custom-role permission BOARDS_READ · read-only

Returns every sprint of a space with its state (planned, active, closed) and dates. Use it to find the active sprint or a sprint id.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "space_id": {
      "type": "number",
      "description": "space id"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "space_id"
  ]
}

create_work_item

Create work item · scope planner:write · minimum role editor · custom-role permission BOARDS_WRITE · write (additive)

Creates a work item (epic, story, task, subtask or bug) in a space and returns it. Use it only when the user asks to create an item.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "space_id": {
      "type": "number",
      "description": "space id"
    },
    "title": {
      "type": "string",
      "description": "item title"
    },
    "type": {
      "type": "string",
      "enum": [
        "epic",
        "story",
        "task",
        "subtask",
        "bug"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "backlog",
        "todo",
        "in_progress",
        "in_review",
        "done",
        "cancelled"
      ]
    },
    "priority": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "urgent"
      ]
    },
    "description": {
      "type": "string"
    },
    "assignee_id": {
      "type": "string"
    },
    "sprint_id": {
      "type": [
        "number",
        "null"
      ]
    },
    "parent_id": {
      "type": [
        "number",
        "null"
      ]
    },
    "estimate_points": {
      "type": "integer"
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "start_date": {
      "description": "ISO date (YYYY-MM-DD)",
      "type": "string"
    },
    "due_date": {
      "description": "ISO date (YYYY-MM-DD)",
      "type": "string"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "space_id",
    "title"
  ]
}

update_work_item

Update work item · scope planner:write · minimum role editor · custom-role permission BOARDS_WRITE · write (overwrites existing data)

Overwrites fields of a work item (status, assignee, sprint, dates, points, priority, labels, position) with patch and returns the updated item. Only the fields in patch change.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "work item id"
    },
    "patch": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "backlog",
            "todo",
            "in_progress",
            "in_review",
            "done",
            "cancelled"
          ]
        },
        "priority": {
          "type": "string",
          "enum": [
            "low",
            "medium",
            "high",
            "urgent"
          ]
        },
        "assignee_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "sprint_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "parent_id": {
          "type": [
            "number",
            "null"
          ]
        },
        "estimate_points": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "labels": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "start_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "due_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "position": {
          "type": "integer"
        }
      },
      "description": "fields to change"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "id",
    "patch"
  ]
}

start_sprint

Start sprint · scope planner:write · minimum role editor · custom-role permission BOARDS_WRITE · write (overwrites existing data)

Starts a planned sprint (planned → active) and returns it. Use it only when the user asks to start the sprint.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "sprint id"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

close_sprint

Close sprint · scope planner:write · minimum role editor · custom-role permission BOARDS_WRITE · write (overwrites existing data)

Closes the active sprint and returns it; unfinished items move back to the backlog (sprint_id = null). Use it only when the user asks to close the sprint.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "sprint id"
    },
    "_token": {
      "description": "legacy user bearer token for multi-tenant mode; omit it when connected with an agent key",
      "type": "string"
    }
  },
  "required": [
    "id"
  ]
}

publish_artifact

Publish HTML artifact · scope artifacts:write · minimum role editor · custom-role permission CONTENT_WRITE · write (additive)

Publishes a self-contained HTML document as a new artifact page and returns { page_id, url, version }; share the url with the user. Use it when the user asks to publish a report, dashboard or prototype. HTML up to 10 MB; HTML containing secrets (API keys, tokens, private keys) is refused.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "artifact title, cut to 200 characters (empty → the HTML <title>)"
    },
    "html": {
      "type": "string",
      "maxLength": 10485760,
      "description": "full HTML document"
    },
    "parent_page_id": {
      "description": "parent page in the same space",
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "generator": {
      "description": "tool that produced the HTML, e.g. claude-code",
      "type": "string"
    }
  },
  "required": [
    "title",
    "html"
  ]
}

update_artifact

Update HTML artifact · scope artifacts:write · minimum role editor · custom-role permission CONTENT_WRITE · write (additive)

Replaces the live HTML of an existing artifact with a new version; earlier versions are kept, and the page id and URL stay the same. Returns { page_id, url, version }. Use it to revise an artifact published with publish_artifact.

Parameters:

Input schema:

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "integer",
      "description": "id of the artifact page"
    },
    "html": {
      "type": "string",
      "maxLength": 10485760,
      "description": "full HTML document of the new version"
    }
  },
  "required": [
    "page_id",
    "html"
  ]
}