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.
| Scope | What it opens | Roles that can hold it |
|---|---|---|
knowledge:read |
listProjects, listDocs, searchKnowledge, readDoc, and the brain tools listBrains, getBrain, getBlueprint, searchBrain |
admin, staff, member |
knowledge:write |
writeDoc and editDoc, with knowledge:read; createProject too, for admin and staff only |
admin, staff, member |
skills:run |
the skill_<name> tools and checkExecution |
admin, staff |
skills:run-contained |
surveyPublicContext and checkSurvey, with both knowledge scopes, for members only; it must be asked for by name |
admin, staff, member |
meetings:read |
getMeetingTranscript |
admin, staff |
apps:invoke |
the open_app__<app> and app__<app>__… tools, for the apps the person can use (a report's run_now for admin and staff, its read_work_log for every role, its save_brief for admin, and, on a report app with drafts (the CRM Agent), its edit_draft, bin_draft, bin_drafts and send_draft for admin and staff, and, on a CRM Agent whose schedule is ready, its list_schedule, schedule_drafts, stop_schedule and set_draft_day for admin and staff) |
admin, staff, member |
apps:write |
the six app source tools, with apps:invoke |
admin, staff |
schedules:manage |
listSchedules, createSchedule, updateSchedule, deleteSchedule, runSchedule |
admin, staff |
synced-folders:sync |
syncFolder; it must be asked for by name (an admin's chat in the Sasha web interface holds it) |
admin |
jobs:run |
listMyClaudeDesktopJobs, getClaudeDesktopJob, askAboutClaudeDesktopJob, reportClaudeDesktopJob, for the person's own jobs |
admin, staff |
jobs:create |
createClaudeDesktopJob, checkClaudeDesktopJob and recordClaudeDesktopJobCheck; it must be asked for by name (the chat in the Sasha web interface holds it), and a job is prepared only in that chat |
admin, staff |
usage:read-team |
getTeamActivity; it must be asked for by name, and the chat in the Sasha web interface does not hold it |
admin; staff when an administrator allows it |
improvements:admin |
no MCP tool; it must be asked for by name | admin |
getDocs, suggestImprovement, checkSuggestion and listSuggestions 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 project, member homes included.
writeDocandeditDocare offered only when the instance has document writing turned on. It is off by default. A member writes their own home and the shared projects where they hold awritegrant. An admin or staff user writes ordinary shared projects only, never a member home, and only when shared-project writing is on.createProjectis offered only to an admin or staff user, because members do not use Sasha chat.- The app source tools are offered only to an admin or staff user, and act only on apps where that person has
manageaccess. - An app's tools appear only when the person has
useormanageaccess 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.
- listSuggestions: list the reports filed on this instance.
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.
Schedules, for admin and staff users:
- listSchedules: list the schedules, with the last result and error.
- createSchedule: add a schedule for a skill, in a time zone.
- updateSchedule: pause, restart or change a schedule.
- deleteSchedule: delete a schedule.
- runSchedule: run a schedule once now.
Synced folders, for admin users:
- syncFolder: sync a folder copied from GitHub now, and see its commit and any error.
Team activity, for admin users (and staff users an administrator allows):
- getTeamActivity: see who was active on this Sasha in the last hours, and how much.
Claude Desktop jobs, for admin and staff users. A job is work in the person's own browser that they approved in Sasha:
- listMyClaudeDesktopJobs: list the person's jobs that are not finished.
- getClaudeDesktopJob: read one approved job and start it.
- askAboutClaudeDesktopJob: record a question about a job.
- reportClaudeDesktopJob: send the report on a job back to Sasha.
- createClaudeDesktopJob: prepare a job in a chat in the Sasha web interface; the person approves it in a Confirm box.
- checkClaudeDesktopJob: read a job's status, questions and report from that chat.
- recordClaudeDesktopJobCheck: record Sasha's own check of a reported job, from that chat.
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:
writeDocandeditDoc. - Research run tools:
surveyPublicContextandcheckSurvey. - App opener tools:
open_app__<app>. - App action tools:
app__<app>__<action>. - App table tools:
app__<app>__<table>__<op>. - Report tools:
app__<app>__run_now,app__<app>__read_work_log,app__<app>__save_brief, and, for a report app with drafts (the CRM Agent),app__<app>__edit_draft,app__<app>__bin_draft,app__<app>__bin_draftsandapp__<app>__send_draft, and, on a CRM Agent whose schedule is ready,app__<app>__list_schedule,app__<app>__schedule_drafts,app__<app>__stop_scheduleandapp__<app>__set_draft_day. - Workspace tool:
createProject, for admin and staff users.
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
getDocssections, one page each underdocs/.
All tools in one table
All tools: every tool, its scopes, and whether it only reads.
Tools by job: every tool grouped by the job it does.
What's new: the changes to the server and this reference, newest first.
The getDocs sections
- What Sasha is and how to work with it: the
overviewsection. - The knowledge base: the
knowledgesection. - Creating and editing documents: the
writingsection. - Editing the source of a Sasha App: the
apps-authoringsection. - What this connection is allowed to do: the
permissionssection. - Running skills: the
skillssection. - Working alongside Bernard (website editing): the
working-with-bernardsection. - Limits and behaviour: the
limitssection. - Suggesting improvements, and what happens next: the
improvementssection. - Brains and blueprints: the
brainssection. - Research runs for a business brain: the
surveyssection. - Report apps: run now, work log and brief: the
reportssection. - Schedules: run a skill at set times: the
schedulessection. - Synced folders: folders copied from GitHub: the
synced-folderssection. - Workspaces: make a knowledge project visible in the sidebar: the
workspacessection. - Claude Desktop jobs: clicks in the person's own browser: the
claude-desktop-jobssection. - Team activity: who used this Sasha, and how much: the
team-activitysection. - What Sasha can do: the
what-sasha-can-dosection.