One record of code, files and pages that people and agents read and write, with lanes and git.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Optional. Bearer <token> from settings, API tokens. Without it the endpoint serves public workspaces read-only; a token is needed to write or read private content.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
List atoms in the current workspace. The `path_prefix`, `body_contains`, `metadata`, `sort`, `direction` and `include_metadata` arguments mirror the same arguments on pages.list.
Order the listing by path (the default), last update, or creation time.
Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own.
Keep only entries whose metadata contains every one of these keys with an equal value; a second key narrows the result. Values are strings, numbers or booleans, and the match is against top-level keys — a key nested inside an object does not answer it. At most 8 keys.
Direction for `sort`. Ascending by default.
Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`.
Carry each entry's metadata object in the response. Off by default, because a metadata bag can be large and a listing is a scan surface.
List atoms in the current workspace. The `path_prefix`, `body_contains`, `metadata`, `sort`, `direction` and `include_metadata` arguments mirror the same arguments on pages.list.
| Argument | Type | Description |
|---|---|---|
| sort | string | Order the listing by path (the default), last update, or creation time. |
| limit | integer | |
| cursor | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| metadata | object | Keep only entries whose metadata contains every one of these keys with an equal value; a second key narrows the result. Values are strings, numbers or booleans, and the match is against top-level keys — a key nested inside an object does not answer it. At most 8 keys. |
| direction | string | Direction for `sort`. Ascending by default. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| path_prefix | string | |
| body_contains | string | |
| include_metadata | boolean | Carry each entry's metadata object in the response. Off by default, because a metadata bag can be large and a listing is a scan surface. |
{
"type": "object",
"properties": {
"sort": {
"enum": [
"path",
"updated_at",
"created_at"
],
"type": "string",
"description": "Order the listing by path (the default), last update, or creation time."
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"cursor": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"metadata": {
"type": "object",
"description": "Keep only entries whose metadata contains every one of these keys with an equal value; a second key narrows the result. Values are strings, numbers or booleans, and the match is against top-level keys — a key nested inside an object does not answer it. At most 8 keys.",
"propertyNames": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
},
"direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Direction for `sort`. Ascending by default."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"path_prefix": {
"type": "string",
"maxLength": 512
},
"body_contains": {
"type": "string",
"maxLength": 200,
"minLength": 3
},
"include_metadata": {
"type": "boolean",
"description": "Carry each entry's metadata object in the response. Off by default, because a metadata bag can be large and a listing is a scan surface."
}
},
"additionalProperties": false
}Read an atom by path or UUID with usage_pages projection. Returns metadata. Pass `section` with a heading's plain text to get back only that heading and the blocks under it, down to the next heading at the same or shallower level; the result then also carries `section: { heading, level, matches }`, and everything else on it is the atom's own, so a section can be read and written straight back.
| Argument | Type | Description |
|---|---|---|
| lane | string | A lane's label. On a write, the patch is stored on the lane, validated against the lane's view, and the trunk is not written. On a read, the body is the trunk's current body with the lane's patches applied, composed now; a conflict exists only where a patch no longer applies or its entity is gone; a moved section is noted in `sections_moved`. A conflicted read carries `conflict` and no body. Omit to act on the trunk. |
| section | string | A heading's plain text (case-insensitive, whitespace-trimmed). When given, the body returned is that heading and every block down to the next heading at the same or shallower level, instead of the whole document, and the result carries a `section` block naming the heading, its level and the match count. No heading of that text answers not_found; several answer validation. |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
List the comment thread for a page or atom.
| Argument | Type | Description |
|---|---|---|
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| target_kind* | string | |
| target_pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
{
"type": "object",
"required": [
"target_kind",
"target_pathOrId"
],
"properties": {
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"target_kind": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"target_pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
}
},
"additionalProperties": false
}Orientation surface: instance metadata, both grounding documents, identity and capabilities, reachable workspaces, sidecar health. Pass `workspace` to ground a named workspace without moving the per-token pointer. Pass a `known_grounding_at` / `known_workspace_grounding_at` you hold and an unchanged document is acknowledged, not resent. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog
| Argument | Type | Description |
|---|---|---|
| instance | string | |
| workspace | string | |
| known_grounding_at | string | ISO-8601 timestamp of the instance grounding document you already hold; when it equals the stored document exactly, the reply acknowledges it as unchanged instead of resending the body, and any other value returns the body. |
| known_workspace_grounding_at | string | ISO-8601 timestamp of the resolved workspace grounding document you already hold; when it equals the stored document exactly, the reply acknowledges it as unchanged instead of resending the body, and any other value returns the body. |
{
"type": "object",
"properties": {
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3
},
"known_grounding_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"description": "ISO-8601 timestamp of the instance grounding document you already hold; when it equals the stored document exactly, the reply acknowledges it as unchanged instead of resending the body, and any other value returns the body."
},
"known_workspace_grounding_at": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
"description": "ISO-8601 timestamp of the resolved workspace grounding document you already hold; when it equals the stored document exactly, the reply acknowledges it as unchanged instead of resending the body, and any other value returns the body."
}
},
"additionalProperties": false
}Browse pages or atoms inside a workspace with faceted filters (tag, author, date range, visibility, metadata containment) and sort by alphabetical, recency, or star count. Viewer-aware: members see everything, anonymous callers see only public entities in public workspaces. 50 items per page, cursor-based. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog
| Argument | Type | Description |
|---|---|---|
| q | string | |
| kind* | string | |
| sort | string | |
| limit | integer | |
| cursor | string | |
| filters | object | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
List instances. Filter: all (default) | public | my | my_admin. public lists an instance that has public reading on, is listed in Discover, is not frozen, and has a workspace that is not private holding a page that is not private. my and my_admin list the caller's own instances (member; admin) with no such gate; all is public plus my. Without a token every filter is public.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| query | string | |
| filter | string |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"query": {
"type": "string",
"maxLength": 200
},
"filter": {
"enum": [
"all",
"public",
"my",
"my_admin"
],
"type": "string"
}
},
"additionalProperties": false
}List workspaces across one or all instances, with the same filters. public lists a workspace when its instance has public reading on, the workspace is not private, its instance is listed in Discover and not frozen, and it holds a page that is not private. my and my_admin list the caller's own workspaces with no such gate; all is public plus my. Without a token every filter is public.
| Argument | Type | Description |
|---|---|---|
| limit | integer | |
| query | string | |
| filter | string | |
| instance_id | string |
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"query": {
"type": "string",
"maxLength": 200
},
"filter": {
"enum": [
"all",
"public",
"my",
"my_admin"
],
"type": "string"
},
"instance_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
}Search instance and workspace metadata + grounding documents. Returns parallel lists for both scopes.
| Argument | Type | Description |
|---|---|---|
| q* | string | |
| limit | integer | |
| scope | string | |
| filter | string |
{
"type": "object",
"required": [
"q"
],
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"scope": {
"enum": [
"instances",
"workspaces",
"both"
],
"type": "string"
},
"filter": {
"enum": [
"all",
"public",
"my",
"my_admin"
],
"type": "string"
}
},
"additionalProperties": false
}Browse the workspace as a file tree, one level at a time: directories, pages, atoms, code trees (expanded at their paths) and library entries. Each node names its kind, entity, current revision and digest; `at` holds the entities exactly at `path`. `surface` keeps that surface only. History: files.history. Anonymous callers see public pages and atoms, and code trees of surface code.
| Argument | Type | Description |
|---|---|---|
| lane | string | A lane label. When given, every node carries `lane: { patched, conflict }` against that lane; a directory is marked when anything below it is. Members only. |
| path | string | A path in the workspace, e.g. "repos/pilot/bin": case kept, slash-separated, no leading slash. Omit or pass "" for the root. |
| limit | integer | Nodes per page, default 100. |
| offset | integer | |
| surface | string | Only entities whose metadata's surface is this one (a tree's files go with their tree). |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
Semantic nearest-neighbors via similarity_edges.
| Argument | Type | Description |
|---|---|---|
| kind* | string | |
| limit | integer | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
{
"type": "object",
"required": [
"pathOrId",
"kind"
],
"properties": {
"kind": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
}
},
"additionalProperties": false
}List incoming + outgoing cross-links for a page or atom.
| Argument | Type | Description |
|---|---|---|
| kind* | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
{
"type": "object",
"required": [
"pathOrId",
"kind"
],
"properties": {
"kind": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
}
},
"additionalProperties": false
}Fetch metadata for a single media item.
| Argument | Type | Description |
|---|---|---|
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| media_id* | string | |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
{
"type": "object",
"required": [
"media_id"
],
"properties": {
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"media_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
}
},
"additionalProperties": false
}List pages in a workspace. `path_prefix` narrows by leading segment; `body_contains` keeps pages whose Markdown holds a literal substring; `metadata` keeps pages whose top-level metadata contains the given scalar keys; `sort` (path | updated_at | created_at) and `direction` order the set; `include_metadata` adds each page's metadata. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog
| Argument | Type | Description |
|---|---|---|
| sort | string | Order the listing by path (the default), last update, or creation time. |
| limit | integer | |
| cursor | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| metadata | object | Keep only entries whose metadata contains every one of these keys with an equal value; a second key narrows the result. Values are strings, numbers or booleans, and the match is against top-level keys — a key nested inside an object does not answer it. At most 8 keys. |
| direction | string | Direction for `sort`. Ascending by default. |
| workspace | string |
Read a page by path or UUID. Returns the Markdown body plus the page metadata object. Pass `section` with a heading's plain text to get back only that heading and the blocks under it, down to the next heading at the same or shallower level; the result then also carries `section: { heading, level, matches }`. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog
| Argument | Type | Description |
|---|---|---|
| lane | string | A lane's label. On a write, the patch is stored on the lane, validated against the lane's view, and the trunk is not written. On a read, the body is the trunk's current body with the lane's patches applied, composed now; a conflict exists only where a patch no longer applies or its entity is gone; a moved section is noted in `sections_moved`. A conflicted read carries `conflict` and no body. Omit to act on the trunk. |
| section | string | A heading's plain text (case-insensitive, whitespace-trimmed). When given, the body returned is that heading and every block down to the next heading at the same or shallower level, instead of the whole document, and the result carries a `section` block naming the heading, its level and the match count. No heading of that text answers not_found; several answer validation. |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
Markdown-level diff between two revisions of the same page or atom. Returns segments (op: equal | insert | delete) plus both Markdown projections.
| Argument | Type | Description |
|---|---|---|
| kind* | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| revision_a_id* | integer | |
| revision_b_id* | integer |
Fetch a specific revision (returns Markdown body).
| Argument | Type | Description |
|---|---|---|
| kind* | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| revision_id* | integer |
{
"type": "object",
"required": [
"kind",
"pathOrId",
"revision_id"
],
"properties": {
"kind": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"revision_id": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}List revisions for a page or atom (cursor-paginated).
| Argument | Type | Description |
|---|---|---|
| kind* | string | |
| limit | integer | |
| cursor | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| pathOrId* | string | Either the path of the page/atom (e.g. "guides/foo" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
{
"type": "object",
"required": [
"kind",
"pathOrId"
],
"properties": {
"kind": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"cursor": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
}
},
"additionalProperties": false
}Hybrid FTS + pgvector + RRF search. Returns Markdown excerpts.
| Argument | Type | Description |
|---|---|---|
| q* | string | |
| limit | integer | |
| scope | string | |
| cursor | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| perspective | string | Only this workspace's pages and atoms the perspective holds (perspectives.list), at paths with its root stripped. |
{
"type": "object",
"required": [
"q"
],
"properties": {
"q": {
"type": "string",
"maxLength": 512,
"minLength": 1
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"scope": {
"enum": [
"workspace",
"all_mine",
"all_public"
],
"type": "string"
},
"cursor": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"perspective": {
"type": "string",
"maxLength": 1100,
"minLength": 1,
"description": "Only this workspace's pages and atoms the perspective holds (perspectives.list), at paths with its root stripped."
}
},
"additionalProperties": false
}Exact-substring search over the Markdown projection of pages and atoms — deterministic, unlike hybrid `search.global`. A needle shorter than 3 characters is rejected. Returns one envelope per matched entity, up to 5 hits each as `{ line, col, snippet }`. `case_sensitive` defaults to false; `scope` is workspace | all_mine | all_public. Details: https://carbonforge.dev/docs/p/api/mcp-tools-catalog
| Argument | Type | Description |
|---|---|---|
| q* | string | |
| kinds | array | |
| limit | integer | |
| scope | string | |
| cursor | string | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| context_lines |
Read a code tree's revision (the current one by default), its metadata and surface, and a page of its entries in path order: path, git mode, size and blob SHA-256, optionally under `path_prefix`. A symlink's blob is its target; a submodule link has no blob and gives its `commit`. With `lane`, `metadata` is the lane's bag if it sets one. Anonymous callers read a public code tree's current one.
| Argument | Type | Description |
|---|---|---|
| lane | string | A lane's label. On a write, the change is stored on the lane — a tree as a manifest delta, a library entry as a blob reference — and the trunk is not written. On a read, the trunk's current state with the lane's patches applied, composed now; where the trunk has moved an entry a lane patch touched, the result carries `conflict` and no entries. Omit to act on the trunk. |
| limit | integer | |
| offset | integer | |
| instance | string | Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own. |
| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| path_or_id* |
List every workspace the calling user is a member of. This is a membership catalogue and not a capability: it is not narrowed by the token, so a listed workspace may still be outside this token's reach. Call cortex.ground for what this token can actually resolve.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Resolve a workspace slug to its id, role, and archived state. 404 when the caller isn't a member (no enumeration).
| Argument | Type | Description |
|---|---|---|
| slug* | string | |
| instance | string |
{
"type": "object",
"required": [
"slug"
],
"properties": {
"slug": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$",
"maxLength": 30,
"minLength": 3
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3
}
},
"additionalProperties": false
}| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
{
"type": "object",
"required": [
"pathOrId"
],
"properties": {
"lane": {
"type": "string",
"pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$",
"description": "A lane's label. On a write, the patch is stored on the lane, validated against the lane's view, and the trunk is not written. On a read, the body is the trunk's current body with the lane's patches applied, composed now; a conflict exists only where a patch no longer applies or its entity is gone; a moved section is noted in `sections_moved`. A conflicted read carries `conflict` and no body. Omit to act on the trunk."
},
"section": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "A heading's plain text (case-insensitive, whitespace-trimmed). When given, the body returned is that heading and every block down to the next heading at the same or shallower level, instead of the whole document, and the result carries a `section` block naming the heading, its level and the match count. No heading of that text answers not_found; several answer validation."
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
}
},
"additionalProperties": false
}| workspace_id | string |
| workspace_slug | string |
{
"type": "object",
"required": [
"kind"
],
"properties": {
"q": {
"type": "string",
"maxLength": 200
},
"kind": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"sort": {
"enum": [
"alphabetical",
"recently_updated",
"recently_created",
"most_starred"
],
"type": "string"
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"cursor": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"filters": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"description": "Keep only entries whose metadata contains every one of these keys with an equal value; a second key narrows the result. Values are strings, numbers or booleans, and the match is against top-level keys — a key nested inside an object does not answer it. At most 8 keys.",
"propertyNames": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
},
"tag_mode": {
"enum": [
"and",
"or"
],
"type": "string"
},
"author_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"date_from": {},
"tag_slugs": {
"type": "array",
"items": {
"type": "string",
"maxLength": 80,
"minLength": 1
},
"maxItems": 20
},
"date_field": {
"enum": [
"created",
"updated"
],
"type": "string"
},
"date_until": {},
"visibility": {
"enum": [
"inherit",
"private",
"any"
],
"type": "string"
}
},
"additionalProperties": false
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"workspace_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"workspace_slug": {
"type": "string",
"pattern": "^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$",
"maxLength": 30,
"minLength": 3
}
},
"additionalProperties": false
}| perspective | string | Only what this perspective holds (perspectives.list), at paths with its root stripped; an anonymous caller sees its public part. Not with surface. |
{
"type": "object",
"properties": {
"lane": {
"type": "string",
"pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$",
"description": "A lane label. When given, every node carries `lane: { patched, conflict }` against that lane; a directory is marked when anything below it is. Members only."
},
"path": {
"type": "string",
"maxLength": 1024,
"description": "A path in the workspace, e.g. \"repos/pilot/bin\": case kept, slash-separated, no leading slash. Omit or pass \"\" for the root."
},
"limit": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Nodes per page, default 100."
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"surface": {
"enum": [
"code",
"adr",
"public-docs",
"internal"
],
"type": "string",
"description": "Only entities whose metadata's surface is this one (a tree's files go with their tree)."
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"perspective": {
"type": "string",
"maxLength": 1100,
"minLength": 1,
"description": "Only what this perspective holds (perspectives.list), at paths with its root stripped; an anonymous caller sees its public part. Not with surface."
}
},
"additionalProperties": false
}| Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
| path_prefix | string |
| body_contains | string |
| include_metadata | boolean | Carry each entry's metadata object in the response. Off by default, because a metadata bag can be large and a listing is a scan surface. |
{
"type": "object",
"properties": {
"sort": {
"enum": [
"path",
"updated_at",
"created_at"
],
"type": "string",
"description": "Order the listing by path (the default), last update, or creation time."
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"cursor": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"metadata": {
"type": "object",
"description": "Keep only entries whose metadata contains every one of these keys with an equal value; a second key narrows the result. Values are strings, numbers or booleans, and the match is against top-level keys — a key nested inside an object does not answer it. At most 8 keys.",
"propertyNames": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
},
"direction": {
"enum": [
"asc",
"desc"
],
"type": "string",
"description": "Direction for `sort`. Ascending by default."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"path_prefix": {
"type": "string",
"maxLength": 512
},
"body_contains": {
"type": "string",
"maxLength": 200,
"minLength": 3
},
"include_metadata": {
"type": "boolean",
"description": "Carry each entry's metadata object in the response. Off by default, because a metadata bag can be large and a listing is a scan surface."
}
},
"additionalProperties": false
}| workspace | string | Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`. |
{
"type": "object",
"required": [
"pathOrId"
],
"properties": {
"lane": {
"type": "string",
"pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$",
"description": "A lane's label. On a write, the patch is stored on the lane, validated against the lane's view, and the trunk is not written. On a read, the body is the trunk's current body with the lane's patches applied, composed now; a conflict exists only where a patch no longer applies or its entity is gone; a moved section is noted in `sections_moved`. A conflicted read carries `conflict` and no body. Omit to act on the trunk."
},
"section": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "A heading's plain text (case-insensitive, whitespace-trimmed). When given, the body returned is that heading and every block down to the next heading at the same or shallower level, instead of the whole document, and the result carries a `section` block naming the heading, its level and the match count. No heading of that text answers not_found; several answer validation."
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
}
},
"additionalProperties": false
}{
"type": "object",
"required": [
"kind",
"pathOrId",
"revision_a_id",
"revision_b_id"
],
"properties": {
"kind": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"pathOrId": {
"type": "string",
"maxLength": 512,
"minLength": 1,
"description": "Either the path of the page/atom (e.g. \"guides/foo\" — no leading slash, lowercase, slash-separated) or the UUID. Paths and UUIDs both resolve inside the workspace this call resolved to: the `workspace` argument when given, otherwise the token's current-workspace pointer."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"revision_a_id": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"revision_b_id": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
}
},
"additionalProperties": false
}| integer |
| case_sensitive | boolean |
{
"type": "object",
"required": [
"q"
],
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"minLength": 3
},
"kinds": {
"type": "array",
"items": {
"enum": [
"page",
"atom"
],
"type": "string"
},
"maxItems": 2,
"minItems": 1
},
"limit": {
"type": "integer",
"maximum": 200,
"exclusiveMinimum": 0
},
"scope": {
"enum": [
"workspace",
"all_mine",
"all_public"
],
"type": "string"
},
"cursor": {
"type": "string",
"maxLength": 2048,
"minLength": 1
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"context_lines": {
"type": "integer",
"maximum": 5,
"minimum": 0
},
"case_sensitive": {
"type": "boolean"
}
},
"additionalProperties": false
}| string |
| The tree's path or its UUID. |
| path_prefix | string |
| revision_id | integer |
| snapshot_id | string | Read the revision this snapshot names (snapshots.cut); not with revision_id or lane. |
{
"type": "object",
"required": [
"path_or_id"
],
"properties": {
"lane": {
"type": "string",
"pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$",
"description": "A lane's label. On a write, the change is stored on the lane — a tree as a manifest delta, a library entry as a blob reference — and the trunk is not written. On a read, the trunk's current state with the lane's patches applied, composed now; where the trunk has moved an entry a lane patch touched, the result carries `conflict` and no entries. Omit to act on the trunk."
},
"limit": {
"type": "integer",
"maximum": 1000,
"minimum": 1
},
"offset": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 0
},
"instance": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Instance (slug or UUID) to resolve a `workspace` slug within. Only meaningful for apex tokens, which have no home instance; instance-locked tokens always resolve within their own."
},
"workspace": {
"type": "string",
"maxLength": 36,
"minLength": 3,
"description": "Workspace (slug or UUID) this call acts in. Overrides the per-token current-workspace pointer for this call only — read-only, it never moves the pointer. Omit to use the pointer set by `me.set_current_workspace`."
},
"path_or_id": {
"type": "string",
"maxLength": 1024,
"minLength": 1,
"description": "The tree's path or its UUID."
},
"path_prefix": {
"type": "string",
"maxLength": 1024
},
"revision_id": {
"type": "integer",
"maximum": 9007199254740991,
"exclusiveMinimum": 0
},
"snapshot_id": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "Read the revision this snapshot names (snapshots.cut); not with revision_id or lane."
}
},
"additionalProperties": false
}