Assistants (MCP)
Point an assistant at your instance, and decide exactly how much of it that assistant can see.
An instance serves the Model Context Protocol at /mcp. An assistant connected to it
can read your lists and tick things off — as much of that as you decided when you cut
the token, and no more.
It is a remote server
Most MCP servers a client knows about are local: the client starts a program on your machine and talks to it over a pipe. Nooks is remote. It is already running, on your own hardware, and a client reaches it over HTTP at the same address you open in a browser.
That difference is most of the setup. There is nothing to install, and the client needs two things from you: the URL, and a token that says who it is acting for.
Every example below uses https://nooks.example/mcp. Replace it with your own
instance's address — the one the binary is listening on, which is :8081 unless you
changed it with --addr. It has to be an address the assistant can
actually reach, so a client on another machine cannot use localhost.
Working on Nooks itself? The app runs on :3001 in development and the instance on
:8081. Point the assistant at :8081.
The short way
Settings → Assistants asks which client you use and how much of the instance it gets, cuts the token, and writes the finished block out for you to copy. It covers the same clients as this page. Read on if your client is not one of them, or if you would rather see what the block is made of.
Cut a token first
Settings → Access tokens → Add a token. Three things decide what the assistant gets:
- Which lists. Either every list you can reach, including ones you make later, or only the ones you pick. A list you do not pick is invisible to the token — it cannot see that the list exists, which is different from being told no.
- What it may do. Read items, add and tick off items, delete items and lists. Three separate answers, and delete is off unless you ask for it.
- When it expires. Ninety days by default.
The secret is shown once, as a line of base64 with no prefix or marker. Nooks keeps only a hash of it, so nobody — including you — can read it back afterwards. Lose it and the answer is to revoke that token and cut another.
The token goes into a configuration file in clear. Do not commit one to a repository. Where a client offers to read it from an environment variable instead, take that offer — Cursor and VS Code both do.
Point a client at it
One command, no file to find:
claude mcp add nooks --transport http https://nooks.example/mcp \
--header "Authorization: Bearer PASTE_YOUR_TOKEN_HERE" \
--scope user--scope user writes it to ~/.claude.json, so the instance is there in every project.
--scope project writes .mcp.json beside your code instead, which is shared with
anybody who clones it — so use user for a token, and project only for a shared
instance whose token is not yours.
Check it with claude mcp list.
Check it worked
Before blaming the client, ask the instance directly. This is the same request a client makes to list the tools:
curl -s -X POST https://nooks.example/mcp \
-H "Authorization: Bearer PASTE_YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'A working token answers with a long list of tool names. not signed in means the
instance was reached and the token was refused, which is the more useful of the two
failures — the address is right and only the credential is wrong.
When it does not work
| What you see | What it usually is |
|---|---|
not signed in | The token is wrong, revoked, or expired. Cut a new one. |
| Connection refused, or a timeout | The client cannot reach the address. A client on another machine cannot use localhost. |
404 on POST, but the URL opens in a browser | Something other than Nooks is on that port, answering every path with the app's HTML. In development that is the dev server on :3001 — use :8081. |
| A certificate error | The instance is on plain HTTP, or using a certificate the client does not trust. See Behind a domain. |
| The server connects but has no tools | Something is in front of Nooks that does not pass Authorization through. Check the reverse proxy. |
| A tool answers "not found" for a list you can see | The token does not reach that list. Its lists are fixed when it is cut. |
| A tool is refused | That ability was left off when the token was cut, or the action needs a signed-in browser. |
Tokens are audited. Settings → Access tokens shows when each one was last used and what it did, which is the quickest way to tell "the client never connected" from "the client connected and was refused".
What the assistant can do
| Tool | What it does |
|---|---|
list_lists | One page of the lists the token reaches, and how many items are open on each |
get_list | What is on one list, ticked and unticked |
create_list | Start a new list |
rename_list | Rename a list |
duplicate_list | Copy a list and everything on it, unticked |
pin_list | Pin a list to the caller's own sidebar, or unpin it |
delete_list | Delete a list and everything on it |
add_item | Put something on a list |
update_item | Change an item's wording, quantity, due date or note |
complete_item | Tick an item off, or put it back |
move_item | Reorder an item within its list |
delete_item | Take an item off a list for good |
search | Find items by what somebody wrote in them |
list_dated_items | What is due in a range of days, across every list |
get_list_shares | Which people and groups a list reaches by name |
set_list_sharing | Change who a list reaches |
list_members | Everyone on this instance |
list_groups | The groups, and who is in them |
whoami | Who the token belongs to |
list_activity | What has happened recently |
mark_activity_read | Clear the unread count |
about_instance | Version, licence, and how much is stored |
Everything an access token can reach, which is everything the REST API gives one. The set is not curated down to what somebody guessed an assistant would want: a household that can tick an item off from a script but not from an assistant has been told the same instance behaves differently depending on which door it came through.
What is missing is missing from a token everywhere. Minting a token, changing a password, adding a member, deciding a join request and every other admin action need a signed-in browser, so a token is refused them over REST too. A test checks this list against the service definitions, so an endpoint cannot be added without deciding whether an assistant can reach it.