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.
  • writeDoc and editDoc are 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 a write grant. An admin or staff user writes ordinary shared projects only, never a member home, and only when shared-project writing is on.
  • createProject is 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 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:

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:

Skills and meetings:

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

Schedules, for admin and staff users:

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:

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.
  • Research run tools: surveyPublicContext and checkSurvey.
  • 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_drafts and app__<app>__send_draft, and, on a CRM Agent whose schedule is ready, app__<app>__list_schedule, app__<app>__schedule_drafts, app__<app>__stop_schedule and app__<app>__set_draft_day.
  • Workspace tool: createProject, for admin and staff users.

Guides

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

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.

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

Built with BernardCookie settings