Sasha MCP reference

What the Sasha MCP is

Sasha is an AI knowledge management system. Each Sasha instance belongs to one organisation. It holds that organisation's knowledge base: projects of markdown documents such as meeting notes, research and reports. An instance can also run the organisation's skills and hold Sasha Apps, small internal applications such as a timesheet.

The Sasha MCP server lets an agent, for example Claude, work with one instance as one person. Everything the agent reads or changes is what that person can read or change in Sasha, and never more.

The usual loop is listProjects, then searchKnowledge, then readDoc. Call getDocs with no arguments for the usage guide that the server itself serves.

Connect

The MCP endpoint is the instance's address followed by /mcp, for example https://your-sasha.example.com/mcp. It uses Streamable HTTP. Every request must carry a bearer token. A connection gets its token in one of two ways:

• OAuth. Add Sasha as a custom connector in the client. The person signs in to Sasha, sees the scopes, and approves them. For the steps in Claude, see Connect Claude to your Sasha.
• A token that the person mints in the Sasha web interface, in Settings, on the Connections tab.

A request without a valid token gets HTTP 401 with a WWW-Authenticate header that points to the OAuth metadata.

How scopes and roles set the tool list

Each connection has a grant: the scopes approved when it was made. On every request, Sasha reduces that grant to what the person holds now. A grant can become narrower over time. It never becomes wider. A scope that the person did not approve, or no longer holds, is not in the grant.

The tool list is the grant. Sasha lists only the tools that this connection may call now. A tool that is not in the list cannot be called: a call returns MCP error -32602: Tool <name> not found. That means the connection does not hold the scope, or a role or switch condition is not true. It does not mean that Sasha lacks the feature. The permissions section of getDocs explains this to the agent.

getDocs, suggestImprovement and checkSuggestion need no scope.

Roles narrow the list further:

• A member sees their own member home and the shared projects where they hold a grant. Admin and staff see every active shared project, but no member home.
• writeDoc and editDoc are offered only to a member, and only when the instance has document writing turned on. It is off by default.
• The app source tools are offered only to an admin or staff user, and act only on apps where that person has manage access.
• An app's tools appear only when the person has use or manage access on that app.

To widen a connection, the person reconnects (OAuth runs again and shows the scopes) or mints a new token. Neither gives more than the person holds in Sasha.

Tools

Knowledge:

• listProjects: list the projects this connection can see.
• listDocs: list the documents in one project.
• searchKnowledge: find documents by text.
• readDoc: read one document, in pages.

Brains (a brain is a folder of documents about one thing, shaped by a blueprint):

• listBrains: list the brains, with their depth by ring.
• getBrain: the contents page of one brain.
• getBlueprint: the documents each kind of brain should have.
• searchBrain: find text inside one brain and its parents.

Guide and feedback:

• getDocs: the usage guide, one section at a time.
• suggestImprovement: report a problem or an idea.
• checkSuggestion: check the status of a report.

Skills and meetings:

• checkExecution: poll a skill run.
• getMeetingTranscript: follow a live meeting.

App source, for admin and staff users who manage an app:

• listAppFiles: list the files of an app and its status.
• readAppFile: read one file.
• writeAppFile: create or replace one file.
• editAppFile: replace one passage in a file.
• deleteAppFile: delete one file.
• checkApp: validate the app.

Tool families

These tools are built for each request, so their names depend on the instance:

• Skill tools: skill_<name>, one for each skill enabled for external use.
• Document write tools: writeDoc and editDoc.
• App opener tools: open_app__<app>.
• App action tools: app__<app>__<action>.
• App table tools: app__<app>__<table>__<op>.

Guides

Worked examples of common jobs, one call at a time:

• Find a fact and cite its source: search, read the document, and give the fact with its path.
• Write a document in your member home: create a note, then change one passage, for members.
• Run a skill and poll for the result: start a skill, poll the run, and read its output.
• Read and change the data of a Sasha App: list, total, add and correct app records.
• Suggest an improvement and track it: report one issue and check what happened to it.
• Work with brains and blueprints: find a brain, see what is missing, and answer from it and its parents.

More reference pages

• Scopes: every scope and its consent text.
• Prompts: the recipe prompts that the server offers.
• Resources: the help articles and the app data resources.
• The getDocs sections, one page each under docs/.

All tools in one table

All tools: every tool, its scopes, and whether it only reads.

The getDocs sections

• What Sasha is and how to work with it: the overview section.
• The knowledge base: the knowledge section.
• Creating and editing documents: the writing section.
• Editing the source of a Sasha App: the apps-authoring section.
• What this connection is allowed to do: the permissions section.
• Running skills: the skills section.
• Working alongside Bernard (website editing): the working-with-bernard section.
• Limits and behaviour: the limits section.
• Suggesting improvements, and what happens next: the improvements section.
• Brains and blueprints: the brains section.
• What Sasha can do: the what-sasha-can-do section.