Sasha MCP reference

getBrain

Read a brain's contents page

The contents page of one brain: its card, depth by ring, and each document (from the blueprint or added by the brain) with state (missing, filled, checked, declined, out of date) and a path; dropped documents with reasons. Read one with readDoc and that path.

Arguments

ArgumentTypeRequiredDescription
brainstringrequiredBrain id from listBrains, in the form "<project>/<folder>"

Scopes

knowledge:read

Annotations

  • Read only: yes
  • Destructive: no

When to use

Call getBrain after listBrains to see what one brain holds and what is still missing. Then read a document with readDoc and its path.

The tool needs the knowledge:read scope.

  • brain is a brain id from listBrains: <project>/<folder>. The card's own path (<project>/<folder>/brain.md) also works.
  • brain in the result repeats the card: id, type, title, blueprint, level, parent (only when this person can read it), card and description (the card's text, up to 1,000 characters).
  • documents is the brain's list: the blueprint's documents, minus the ones the card drops, plus the ones it adds. from is blueprint or added; an added document also has the card's reason. The file is <id>.md in the brain's folder. Other files in the folder are not listed here, but searchBrain finds them.
  • dropped lists the blueprint documents that the card drops, each with its reason. They do not count in depth.
  • state is one of missing, filled, checked, declined or out of date. When more than one applies, the order is: declined, out of date, checked, filled. A file with only frontmatter counts as missing, with exists: true.
  • A document is out of date when its last change, or its checked date if that is later, is older than its outOfDateAfterDays.
  • summary, checkedOn and checkedBy come from the document's own frontmatter fields summary, checked and checkedBy. A document's state is never stored in brain.md. lastChange is the time the file last changed.
  • When the brain has a readable parent, each missing document has parentCovers: the parent's filled or checked documents that cover the same spine domain. An empty list means the parent does not cover it either.
  • newerBlueprint is null, or says that a newer version of the blueprint is available, with the documents it would add (wouldAdd) and remove (wouldRemove). It is information only: nothing changes until someone edits the card.
  • warnings (only when there is something to say) names entries in the card's add or drop lists that were skipped, and why.
  • A card that names a blueprint this release does not have returns warnings, depth: null and no documents.

Example

{ "brain": "northwind-advisory/brains/website" }

This website brain uses site@1, drops design-system and adds events. The response below shows 4 of its 14 documents.

{
  "brain": {
    "id": "northwind-advisory/brains/website",
    "type": "site",
    "title": "Northwind Advisory website",
    "blueprint": "site@1",
    "level": "sasha",
    "parent": "northwind-advisory/brains/business",
    "card": "northwind-advisory/brains/website/brain.md",
    "description": "The public website of Northwind Advisory, for public-sector buyers."
  },
  "blueprint": { "id": "site", "ref": "site@1", "title": "Website" },
  "depth": [
    { "ring": "Public Context", "stage": "Scope", "documents": 10, "filled": 2, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 8 },
    { "ring": "System Integration", "stage": "Embed", "documents": 3, "filled": 0, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 3 },
    { "ring": "Flow", "stage": "Flow", "documents": 1, "filled": 0, "checked": 0, "declined": 0, "outOfDate": 0, "missing": 1 }
  ],
  "documents": [
    {
      "id": "about", "title": "About", "ring": "Public Context", "deepens": [1, 4], "from": "blueprint",
      "path": "northwind-advisory/brains/website/about.md", "exists": true, "state": "filled",
      "filled": true, "checked": false, "declined": false, "outOfDate": false,
      "summary": "Who we are, in two paragraphs.", "lastChange": "2026-09-01T10:00:00.000Z",
      "checkedOn": null, "checkedBy": null
    },
    {
      "id": "voice", "title": "Voice", "ring": "Public Context", "deepens": [13], "from": "blueprint",
      "path": "northwind-advisory/brains/website/voice.md", "exists": false, "state": "missing",
      "filled": false, "checked": false, "declined": false, "outOfDate": false,
      "summary": null, "lastChange": null, "checkedOn": null, "checkedBy": null,
      "parentCovers": [
        {
          "brain": "northwind-advisory/brains/business",
          "document": "voice-and-forbidden-language",
          "title": "Voice and forbidden language",
          "state": "checked",
          "path": "northwind-advisory/brains/business/voice-and-forbidden-language.md"
        }
      ]
    },
    {
      "id": "offer", "title": "Offer", "ring": "Public Context", "deepens": [2], "from": "blueprint",
      "path": "northwind-advisory/brains/website/offer.md", "exists": true, "state": "filled",
      "filled": true, "checked": false, "declined": false, "outOfDate": false,
      "summary": "Three services, with prices from 4,500 GBP.", "lastChange": "2026-09-20T10:00:00.000Z",
      "checkedOn": null, "checkedBy": null
    },
    {
      "id": "events", "title": "Events", "ring": "Public Context", "deepens": [2, 4], "from": "added",
      "reason": "The site sells places at our public workshops",
      "path": "northwind-advisory/brains/website/events.md", "exists": false, "state": "missing",
      "filled": false, "checked": false, "declined": false, "outOfDate": false,
      "summary": null, "lastChange": null, "checkedOn": null, "checkedBy": null,
      "parentCovers": [
        {
          "brain": "northwind-advisory/brains/business",
          "document": "offer-surface",
          "title": "Offer surface",
          "state": "filled",
          "path": "northwind-advisory/brains/business/offer-surface.md"
        }
      ]
    }
  ],
  "dropped": [
    { "id": "design-system", "title": "Design system", "ring": "Public Context", "reason": "The site uses a bought theme with no design system of our own" }
  ],
  "newerBlueprint": null
}

Here the site has no Voice document, but the parent business brain has a checked one. Read it with readDoc and the path in parentCovers.

Refusals and what to do

  • Error in getBrain: Not found: there is no brain with this id that this person can read. The project may not exist or may be hidden, the folder may have no brain.md card, or the path may not be allowed. The answer is the same in each case. Call listBrains and use an id from that list.
  • If the connection does not hold knowledge:read, the tool is not in your tool list, and a call to it returns MCP error -32602: Tool getBrain not found. Read the permissions section of getDocs. A scope is never added to an existing connection: the person must reconnect, or mint a new token, with knowledge:read.

Related

  • listBrains gives the brain ids.
  • readDoc reads a document with the path from this result, or the card itself with card.
  • getBlueprint says what each blueprint document should hold.
  • searchBrain searches inside this brain.
  • getDocs explains brains in its brains section.
made with bernard

Cookie settings