Use Notes from any agent (MCP)
Connect Claude Code, Qoder, Cursor or any MCP client to Venom Notes with a Venom API key, so your agents can search, read and write your organisation's notes.
Venom Notes is your organisation's knowledge vault: markdown notes with [[wikilinks]], in your personal vault and the
organisation vault. Its MCP server lets any agent that speaks the Model Context Protocol use it, so a fact
Claude Code learns on Monday is there for Cursor and venom on Tuesday.
- Endpoint:
https://cloud.usevenom.dev/globe/mcp. It uses Streamable HTTP, is stateless, and takes JSON-RPC over POST. A self-hosted Venom Cloud serves the same path on its own origin. - Credentials: a Venom API key sent as a bearer token, or, for apps that sign in through a browser (Claude.ai, ChatGPT), OAuth. The endpoint never reads a cookie.
- Add-on: Notes is an add-on. If your organisation hasn't added it, the handshake still works and every tool answers with a short message saying where to add it.
Get a key
In the console, open Settings → API keys and create a key with This key is mine switched on. That makes it a personal key, so the agent sees what you see:
| Key | Vaults the agent can reach |
|---|---|
| Personal key ("This key is mine") | your personal vault (me) and the organisation vault |
| Team or service key | the organisation vault only, never anyone's personal vault |
Another member's personal vault is never reachable, whatever the key. Keep the key out of files you commit: the examples below read it from an environment variable.
export VENOM_GLOBE_KEY=vck_… # the key you just createdClaude Code
claude mcp add --transport http globe https://cloud.usevenom.dev/globe/mcp \
--header "Authorization: Bearer $VENOM_GLOBE_KEY"Add --scope user to have it in every project. claude mcp list should show globe as connected.
venom
Nothing to set up. Once you've signed in with venom cloud login (which makes a personal key), every venom session
registers the globe server (/workspace/mcp/globe) with that key, beside every other Venom product
(What agents connect to by default). Its tools are deferred like any other MCP server's: the agent finds them
with tool_search when it needs them, so they don't add to every request's tool list. venom doctor lists it under
MCP servers.
VENOM_GLOBE_MCP=offleaves it out.- An MCP server of your own called
globetakes its place. - If your organisation's policy has an MCP allowlist without
globe, it is left out.
Cursor, Qoder and other clients (mcpServers JSON)
Most clients read the same mcpServers shape. Cursor reads ~/.cursor/mcp.json (or .cursor/mcp.json in a
project). In Qoder, add a server in its MCP settings and paste the same entry.
{
"mcpServers": {
"globe": {
"type": "http",
"url": "https://cloud.usevenom.dev/globe/mcp",
"headers": { "Authorization": "Bearer ${VENOM_GLOBE_KEY}" }
}
}
}If your client does not expand ${VENOM_GLOBE_KEY}, paste the key itself, and keep that file out of version
control. A client that only has "url" and no "type" treats it as HTTP as well.
Claude.ai and ChatGPT (OAuth)
Apps that connect from the web sign you in through your browser instead of taking a key. Give them the endpoint URL,
https://cloud.usevenom.dev/globe/mcp, and nothing else:
- Claude.ai: Settings → Connectors → Add custom connector, then paste the URL.
- ChatGPT: Settings → Connectors (developer mode) → Create, then paste the URL with OAuth as the authentication.
The app registers itself and opens a Venom Cloud page (/globe/oauth/authorize). If you're signed out, you sign in first. The page names the
app, your organisation, what the app may do and where it returns. Allow connects it as you. It can then reach what
your personal key would reach: your own vault and the organisation vault. Deny sends the app away
with nothing.
| What the app asked for | What it may do |
|---|---|
globe:read |
search and read notes |
globe:write |
write notes in the vaults you can write |
An app connected with globe:read only gets a short refusal from globe_note_write.
Each app you connect is listed in Settings → Connected apps (/settings/connected-apps) in the console, with when you last used it.
Disconnect ends it at once, along with every token it holds. Leaving the organisation ends it too.
How it is built, for the curious: OAuth 2.1 with dynamic client registration (RFC 7591) and authorization codes with
PKCE (S256 only). Discovery goes through /.well-known/oauth-protected-resource (RFC 9728) and
/.well-known/oauth-authorization-server (RFC 8414). Access tokens last an hour and are bound to /globe/mcp.
Refresh tokens last 30 days and are replaced on every use. Venom keeps only hashes of codes and tokens. A code used
twice, or an old refresh token used again, disconnects the app: one of the two copies wasn't the app's.
What the agent can do
| Tool | Arguments | What it does |
|---|---|---|
globe_vault_list |
none | lists the vaults you can reach, how many notes each has, and whether you can write to it |
globe_note_search |
query, vault?, limit? (1–25, default 8) |
full-text search across every vault you can read, or one vault; each hit has its path, id and a snippet |
globe_note_get |
id or path, vault?, offset?, max_chars? |
one note: its properties, body, links and backlinks. Long notes come in pages, and the answer says where the next page starts |
globe_note_list |
vault?, folder?, cursor?, limit? |
the notes in a vault or folder, a page at a time |
globe_note_write |
vault, path, body, mode (create, append, replace) |
writes a note, in a vault you can write. Anywhere else it is refused and nothing changes |
globe_note_edit |
id (or vault and path), edits (1–50) |
changes part of a note with anchored edits (replace, insert_before, insert_after, prepend, append, replace_range), all or none, checked against the note as it is now. See Venom for agents |
globe_suggestion_create |
vault, suggestions (1–50) |
files suggestions in the vault's Inbox: a new note, text to add, a link between two notes, a new body for a note, or a conflict. Nothing changes until a person applies them, and the Inbox shows them as "Suggested by <your app> via MCP". Works in any vault you can read |
globe_note_ask |
question, vault? |
finds the notes that answer a question, by meaning and keywords plus the notes they link to, and returns them as numbered citations. It does not write an answer: your agent's own model does that. See How Ask finds notes |
globe_note_related |
id (or path and vault), limit? (1–25, default 10) |
the notes next to one note, each with why: links, backlinks, parent page and sub-pages, its database page and sibling rows, relations, and notes similar by meaning |
Every tool that creates, changes, reads, lists or searches pages or databases answers with an absolute url for each
one: https://<your cloud>/globe/vault/<id>-<slug> for a note or a database row, and /globe/db/<id> for a database.
The origin is the cloud's configured address (VENOM_CLOUD_ORIGIN), else the address the request came to. A text answer
has a url line or url in each item; JSON answers have a url field. The server instructions tell the agent to give you
the link after it creates or changes a page, so you don't have to ask.
A note's name is its path, so \ : * ? " < > | # ^ [ ] can't be in a path. A database row's title may hold them: they
are replaced in the row's name (: becomes -, the others are dropped), so a headline with a colon or a question mark
is saved, not refused.
vault is me, org, or a team vault's id from globe_vault_list. Each note is also a resource,
globe://note/<id>, for clients that read resources. Answers are cut to a size that fits an agent's context, and a
cut answer says how to read the rest.
Limits and safety
- Rate limit: 120 requests a minute per key. Past that the endpoint answers
429withretry-after. - Request size: 1 MiB per request; a note's body is at most 200 KB.
- Secrets: a write that contains a credential (an API key, a token, a private key) is refused, so an agent can't paste one into a note.
- Audit: every write is recorded in the organisation's audit log under the key that made it
(
mcp:key:<id>), with ids and content hashes, never the text. - No sessions: each request stands alone.
GET(server-sent events) answers405, so clients fall back to plain POST.
Troubleshooting
| You see | Why | Fix |
|---|---|---|
401 with www-authenticate: Bearer … resource_metadata=… |
no key, a wrong one, or a revoked or expired one | check the Authorization header and the key in Settings → API keys |
| a connected app stops working | you disconnected it, it was used from two places, or you left the organisation | connect it again from the app |
| a tool says "Venom Notes is an add-on your organisation has not bought" | the organisation hasn't added Notes | an owner or billing admin adds it at the link in the message (Settings → Billing) |
| "This credential has no personal vault" | you used a team or service key | create a personal key ("This key is mine") |
globe_note_write answers "you can read … but not write it" |
your role may read that vault, not write it | write to a vault globe_vault_list marks "you can write", or ask someone who can |
429 |
more than 120 requests in a minute on this key | wait for retry-after seconds |