Carbon Forge

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

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "path_prefix": {
      "type": "string",
      "maxLength": 512
    },
    "body_contains": {
      "type": "string",
      "minLength": 3,
      "maxLength": 200
    },
    "sort": {
      "type": "string",
      "enum": [
        "path",
        "updated_at",
        "created_at"
      ],
      "description": "Order the listing by path (the default), last update, or creation time."
    },
    "direction": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Direction for `sort`. Ascending by default."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      },
      "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."
    },
    "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."
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "additionalProperties": false
}

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

{
  "type": "object",
  "properties": {
    "pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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."
    },
    "section": {
      "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.",
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "lane": {
      "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.",
      "type": "string",
      "pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$"
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "pathOrId"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "path_prefix": {
      "type": "string",
      "maxLength": 512
    },
    "body_contains": {
      "type": "string",
      "minLength": 3,
      "maxLength": 200
    },
    "sort": {
      "type": "string",
      "enum": [
        "path",
        "updated_at",
        "created_at"
      ],
      "description": "Order the listing by path (the default), last update, or creation time."
    },
    "direction": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "description": "Direction for `sort`. Ascending by default."
    },
    "metadata": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      },
      "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."
    },
    "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."
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "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.

{
  "type": "object",
  "properties": {
    "pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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."
    },
    "section": {
      "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.",
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "lane": {
      "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.",
      "type": "string",
      "pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$"
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "pathOrId"
  ],
  "additionalProperties": false
}

Hybrid FTS + pgvector + RRF search. Returns Markdown excerpts.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "scope": {
      "type": "string",
      "enum": [
        "workspace",
        "all_mine",
        "all_public"
      ]
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "perspective": {
      "description": "Only this workspace's pages and atoms the perspective holds (perspectives.list), at paths with its root stripped.",
      "type": "string",
      "minLength": 1,
      "maxLength": 1100
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "q"
  ],
  "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

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 3,
      "maxLength": 200
    },
    "scope": {
      "type": "string",
      "enum": [
        "workspace",
        "all_mine",
        "all_public"
      ]
    },
    "kinds": {
      "minItems": 1,
      "maxItems": 2,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "page",
          "atom"
        ]
      }
    },
    "context_lines": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5
    },
    "case_sensitive": {
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "q"
  ],
  "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

{
  "type": "object",
  "properties": {
    "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",
      "minLength": 3,
      "maxLength": 30,
      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$"
    },
    "kind": {
      "type": "string",
      "enum": [
        "page",
        "atom"
      ]
    },
    "sort": {
      "type": "string",
      "enum": [
        "alphabetical",
        "recently_updated",
        "recently_created",
        "most_starred"
      ]
    },
    "q": {
      "type": "string",
      "maxLength": 200
    },
    "filters": {
      "type": "object",
      "properties": {
        "tag_slugs": {
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          }
        },
        "tag_mode": {
          "type": "string",
          "enum": [
            "and",
            "or"
          ]
        },
        "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": {},
        "date_until": {},
        "date_field": {
          "type": "string",
          "enum": [
            "created",
            "updated"
          ]
        },
        "visibility": {
          "type": "string",
          "enum": [
            "inherit",
            "private",
            "any"
          ]
        },
        "metadata": {
          "type": "object",
          "propertyNames": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "additionalProperties": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "number"
              },
              {
                "type": "boolean"
              }
            ]
          },
          "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."
        }
      },
      "additionalProperties": false
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "kind"
  ],
  "additionalProperties": false
}

Semantic nearest-neighbors via similarity_edges.

{
  "type": "object",
  "properties": {
    "pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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."
    },
    "kind": {
      "type": "string",
      "enum": [
        "page",
        "atom"
      ]
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "pathOrId",
    "kind"
  ],
  "additionalProperties": false
}

List incoming + outgoing cross-links for a page or atom.

{
  "type": "object",
  "properties": {
    "pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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."
    },
    "kind": {
      "type": "string",
      "enum": [
        "page",
        "atom"
      ]
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "pathOrId",
    "kind"
  ],
  "additionalProperties": false
}

List revisions for a page or atom (cursor-paginated).

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "page",
        "atom"
      ]
    },
    "pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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."
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    },
    "cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "kind",
    "pathOrId"
  ],
  "additionalProperties": false
}

Fetch a specific revision (returns Markdown body).

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "page",
        "atom"
      ]
    },
    "pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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."
    },
    "revision_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "kind",
    "pathOrId",
    "revision_id"
  ],
  "additionalProperties": false
}

Markdown-level diff between two revisions of the same page or atom. Returns segments (op: equal | insert | delete) plus both Markdown projections.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "page",
        "atom"
      ]
    },
    "pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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."
    },
    "revision_a_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "revision_b_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "kind",
    "pathOrId",
    "revision_a_id",
    "revision_b_id"
  ],
  "additionalProperties": false
}

Fetch metadata for a single media item.

{
  "type": "object",
  "properties": {
    "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": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "media_id"
  ],
  "additionalProperties": false
}

List the comment thread for a page or atom.

{
  "type": "object",
  "properties": {
    "target_kind": {
      "type": "string",
      "enum": [
        "page",
        "atom"
      ]
    },
    "target_pathOrId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "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": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "target_kind",
    "target_pathOrId"
  ],
  "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

{
  "type": "object",
  "properties": {
    "instance": {
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "workspace": {
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "known_grounding_at": {
      "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.",
      "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))$"
    },
    "known_workspace_grounding_at": {
      "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.",
      "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))$"
    }
  },
  "additionalProperties": false
}

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.

{
  "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).

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 3,
      "maxLength": 30,
      "pattern": "^[a-z0-9](?:[a-z0-9-]{0,28}[a-z0-9])?$"
    },
    "instance": {
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "enum": [
        "all",
        "public",
        "my",
        "my_admin"
      ]
    },
    "query": {
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "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.

{
  "type": "object",
  "properties": {
    "filter": {
      "type": "string",
      "enum": [
        "all",
        "public",
        "my",
        "my_admin"
      ]
    },
    "query": {
      "type": "string",
      "maxLength": 200
    },
    "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)$"
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "additionalProperties": false
}

Search instance and workspace metadata + grounding documents. Returns parallel lists for both scopes.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "scope": {
      "type": "string",
      "enum": [
        "instances",
        "workspaces",
        "both"
      ]
    },
    "filter": {
      "type": "string",
      "enum": [
        "all",
        "public",
        "my",
        "my_admin"
      ]
    },
    "limit": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 200
    }
  },
  "required": [
    "q"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "path_or_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "The tree's path or its UUID."
    },
    "revision_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "snapshot_id": {
      "description": "Read the revision this snapshot names (snapshots.cut); not with revision_id or lane.",
      "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)$"
    },
    "path_prefix": {
      "type": "string",
      "maxLength": 1024
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "lane": {
      "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.",
      "type": "string",
      "pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$"
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "required": [
    "path_or_id"
  ],
  "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.

{
  "type": "object",
  "properties": {
    "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."
    },
    "lane": {
      "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.",
      "type": "string",
      "pattern": "^(?=.{1,255}$)[a-z0-9][a-z0-9._-]{0,127}(\\/[a-z0-9][a-z0-9._-]{0,127})*$"
    },
    "surface": {
      "description": "Only entities whose metadata's surface is this one (a tree's files go with their tree).",
      "type": "string",
      "enum": [
        "code",
        "adr",
        "public-docs",
        "internal"
      ]
    },
    "perspective": {
      "description": "Only what this perspective holds (perspectives.list), at paths with its root stripped; an anonymous caller sees its public part. Not with surface.",
      "type": "string",
      "minLength": 1,
      "maxLength": 1100
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "Nodes per page, default 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "workspace": {
      "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`.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    },
    "instance": {
      "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.",
      "type": "string",
      "minLength": 3,
      "maxLength": 36
    }
  },
  "additionalProperties": false
}