FAQ
Frequently asked questions
Connecting
Can I add it as a connector on claude.ai?
Not today. Custom connectors on claude.ai support OAuth only and cannot send custom headers. The Goono MCP server authenticates with the X-Goono-Key header.
Why does Claude Desktop need mcp-remote?
Claude Desktop cannot attach custom headers to remote HTTP servers. mcp-remote runs as a local stdio server and relays requests with the header attached. See the Claude Desktop tab in Connect a client.
I have several workspaces.
Keys are issued per workspace and user, so issue one key per workspace and register separate servers (for example goono-lab-a, goono-lab-b).
I keep getting 401.
Check, in order: the header name is X-Goono-Key, the key starts with gno_live_ or gno_test_, and the key is neither expired nor revoked. The server only checks that the header exists and has a valid prefix; the Goono backend decides validity.
Tools
How do I read a note's contents?
get_note_file is the only way. OCR text is not exposed.
What about files over 512KB? There is no way to read them. The tool returns a result with only the size instead of an error, and the LLM reports that the file is N bytes and cannot be read. The size is measured on the stored ciphertext.
Filtering by tag returns nothing.
There is no tag-list API, so the LLM may have guessed a value. Pick exact values from tags in list_notes results and filter again. Tag filtering is partial-match.
A note I saw in a list now returns 404.
Notes can be moved to another folder or project from the Goono app or by another tool. The noteId stays the same but projectId and folderId change. Use search to find its current location.
Folder deletion is rejected with 409.
Only empty folders can be deleted. Move the notes out with move_note, unlink any GitHub repository, then retry.
The LLM keeps asking for confirmation before writing. That is intended. Folder writes and note moves change what users see, so the server instructions and tool descriptions require presenting a plan and getting approval first.
Operations
I hit the rate limit often.
Usually the content bucket (60 per minute). Read files sequentially and only the ones you need. Rate limits has more tips.
There are fields I don't recognize in responses. The MCP server forwards Goono backend JSON unchanged. The backend may add fields and enum values in a backward-compatible way, so ignore what you don't know.
Can I run the server locally?
There is no npm package. Clone the repository and run pnpm install && pnpm dev (http://localhost:3000/mcp). To demo without a backend, run GOONO_MOCK=1 pnpm dev for sample-data mode.