---
title: Use Notes from any agent (MCP)
description: 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.
section: integrations
order: 60
audience: [user, operator, agent]
sources: [services/nodejs-cloud/app/globe/mcp/route.ts, services/nodejs-cloud/lib/globe/mcp, services/nodejs-cloud/lib/oauth, services/nodejs-cloud/migrations/0118_globe_oauth.sql, docs/adr/0048-knowledge-add-on.md]
features: [cloud.globe-mcp, cloud.globe, cloud.console-globe, cloud.well-known]
---

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.

```bash
export VENOM_GLOBE_KEY=vck_…   # the key you just created
```

## Claude Code

```bash
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](/docs/cloud/agent-defaults)). 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=off` leaves it out.
- An MCP server of your own called `globe` takes 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.

```json
{
  "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](/docs/cloud/workspace-mcp#anchored-edits) |
| `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](/docs/globe/ask) |
| `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 `429` with `retry-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) answers `405`, 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 |
