Claude, and other agents

There is an MCP server on top of everything else here. A client that speaks MCP can work in one of your workspaces — reading notes, writing them, answering the comments on them — and the whole of setting it up is pasting one address and pressing Allow.

Connecting

Paste https://goscribi.com/mcp into a client that takes an MCP server address. It will send you here to sign in, ask which workspace and what it may do, and you press Allow. Nothing is shared until you do, and no secret is ever copied — the client gets a token of its own, for one workspace, which you can end at any time under Your account → API keys.

For something with no browser — a script, a machine somewhere — use a key instead. Make one under Your account → API keys and give it to the bundled bridge:

claude mcp add go-scribi \
  --env GO_SCRIBI_URL=https://goscribi.com \
  --env GO_SCRIBI_KEY=$GO_SCRIBI_KEY \
  -- npx -y go-scribi-mcp

A key that reaches more than one workspace needs to be told which: GO_SCRIBI_WORKSPACE=<id>, or point the client at /mcp/w/<id>.

The tools

Sixteen, on purpose. This application has well over a hundred endpoints inside a workspace, and wrapping them one for one would make an agent worse at using it, not better — so the tools are shaped like things somebody asks for.

Tool	Needs	What it does
`find_notes`	read	Search this workspace and get back the notes that match, with the sentence that matched
`read_note`	read	Read one note whole, whatever kind it is: a Markdown body, a checklist's rows, a board's columns and cards, or a mind map's tree
`read_subject`	read	Everything written about a subject
`list_places`	read	Where things can go: the folders in this workspace, and
`whoami`	read	Who this connection acts as, which workspace it is pointed at, and whether it may write
`note_history`	read	What has changed on a note, when, and by whom
`write_note`	write	Make a note, or replace what one says
`edit_note`	write	Change part of a note: add or reword a checklist row, a board card, a column, or a map node, or remove one
`tick`	write	Check or uncheck a checklist row
`move_things`	write	Put something somewhere else: file a note in a folder, put a folder inside another one, move a card to another column, or reorder a row
`make_folder`	write	Make a folder to file notes in
`upload_file`	comment	Put a picture or a document on a note and get back the Markdown that shows it
`build`	write	Make a whole folder tree and the notes in it, in ONE call, all or nothing
`properties`	read	What notes in this workspace can say about themselves
`repeats`	write	What comes back, and when
`comments`	comment	The conversations on a note

What a connection is offered

A tool a connection may not use is not offered at all, rather than offered and then refused — an agent that cannot write should not spend its time discovering that halfway through a job. The list is built from what the credential can actually do:

read — 7 tools: find_notes, read_note, read_subject, list_places, whoami, note_history, and properties
comment — 9 tools: find_notes, read_note, read_subject, list_places, whoami, note_history, upload_file, properties, and comments
write — 16 tools: find_notes, read_note, read_subject, list_places, whoami, note_history, write_note, edit_note, tick, move_things, make_folder, upload_file, build, properties, repeats, and comments

A key's level and a connection's scope both only ever LOWER what their holder may do — see what a credential may do.

Prompts

Ready-made jobs a client can offer, rather than things you have to describe each time.

my_week: What has been going on in this workspace lately.
whats_overdue: Anything with a date that has passed, or work that has stalled.
review_comments: Answer what people have asked about a note. Takes note.
about: Everything written about a subject, pulled together. Takes subject.
tidy_a_list: Go through a checklist and bring it up to date. Takes note.

The endpoint itself

POST /mcp: A JSON-RPC 2.0 request, or an array of them. A batch answers with an array of only the messages that had ids; if none did, 202 and no body.
POST /mcp/w/:workspace_id: The same, naming the workspace — for a credential that reaches more than one. Without it, a connection reaching several is told no_workspace, with the ids it can see.
GET /mcp: 405. There are no server-initiated messages.
DELETE /mcp: 204. There is no session to close, said out loud.

How a client finds its way in

An unauthenticated request answers 401 with a WWW-Authenticate header naming /.well-known/oauth-protected-resource, which names the authorization server, which names its endpoints. That chain is what the MCP specification asks for, and it is why pasting one address is enough.

WWW-Authenticate: Bearer realm="Go Scribi",
  resource_metadata="https://goscribi.com/.well-known/oauth-protected-resource"

Registration is dynamic and needs no secret: clients are public and prove themselves with PKCE. Tokens last an hour and refresh for ninety days, and a refresh token that is used twice ends the whole connection.

The rest of the API

Notes A note is text, a checklist, a board or a map. These are the calls that make, read, change and bin one, whichever kind it is.
Checklist rows The rows of a checklist: their text, their own notes, what is ticked, and where each one sits in the tree.
Board columns and cards A board is cards in columns. Cards carry a description, an assignee, a due date and an estimate; columns carry a WIP limit and which one finishes.
Map nodes The nodes of a mind map: the same tree a checklist has, with a side and a colour.
Comments The conversations on a note — what somebody asked about a particular sentence, and everything said back. A thread is a conversation; a reply is one message in it.
Repeating tasks What comes back, and when. Rules are RFC 5545 `RRULE` strings — the ones every calendar exchanges — so a rule you already have can be handed over unchanged, and one you are given can be fed to a calendar.
Building a tree in one call Make a folder tree and the notes in it in one request, all or nothing. Name things with your own reference ids so a note can go in a folder the same call is about to make, try it without doing it, and send an idempotency key so a lost reply cannot build it twice.
Note properties Fields on a note itself — a review date, a status, where it came from — rather than words inside it. Every one is optional, and everything here is keyed by a property's KEY, which never changes when it is renamed.
History and undo Every write leaves a version. These read them, read what the note SAID at one of them, and take back a change.
Finding things Search, subjects, folders and templates: the calls a program makes before it knows which note it wants.
Workspaces and limits Which workspaces a credential reaches, what it may do in one, and what the plan allows.