Sasha MCP reference

listProjects

List knowledge projects

List the knowledge projects you are allowed to see in this Sasha instance. Start here to discover what knowledge exists, then use listDocs or searchKnowledge.

Arguments

No arguments.

Scopes

knowledge:read

Annotations

  • Read only: yes
  • Destructive: no

When to use

Call listProjects at the start of a session. It tells you which projects exist for this connection. The core loop is listProjects, then searchKnowledge, then readDoc.

The tool needs the knowledge:read scope. It takes no arguments.

The list depends on the role of the person who connected:

  • A member sees their own member home and each ordinary project where they hold a grant.
  • Admin and staff see every active ordinary project. They never see a member home.

Each project has a kind: ordinary for a shared project, or member-home for a member's own home.

The id, name and projectId fields hold the same value. Pass that value as project to the other knowledge tools.

A project that holds folders copied from GitHub also has a syncedFolders list. Each entry has folder (the folder name in the project), source (owner/repo@branch, or owner/repo@branch:path for one folder of the repository) and lastSynced (the time of the last good sync in UTC, or null). A project without synced folders has no syncedFolders field. A synced folder is read-only: its documents change in GitHub. An admin can sync one now with syncFolder.

For an admin or staff connection that holds knowledge:write, each project also has hasWorkspace: true when the project has a workspace in the Sasha web interface, where its documents show in the sidebar. For false, createProject makes one. Other connections get no hasWorkspace field.

Example

The request has no arguments.

{}
{
  "projects": [
    {
      "id": "northwind-advisory", "name": "northwind-advisory", "projectId": "northwind-advisory", "kind": "ordinary",
      "syncedFolders": [
        { "folder": "handbook", "source": "northwind/policies@main:docs/handbook", "lastSynced": "2026-10-21T03:12:00.000Z" }
      ]
    },
    { "id": "client-onboarding", "name": "client-onboarding", "projectId": "client-onboarding", "kind": "ordinary" },
    { "id": "member-14", "name": "member-14", "projectId": "member-14", "kind": "member-home" }
  ]
}

Refusals and what to do

  • 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 listProjects 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.
  • An empty projects list is not an error. It means that this person can see no project. A member needs a grant from an admin to see a shared project.

Related

  • listDocs lists the documents in one project.
  • searchKnowledge searches every project in this list, or one of them.
  • readDoc reads one document.
  • syncFolder syncs a folder copied from GitHub now (admin only).
  • createProject gives a project a workspace in the Sasha web interface (admin and staff).
  • getDocs explains the knowledge layout in its knowledge section.
Built with BernardCookie settings