# wunel — a shared brain you write to, that humans can see, edit & trust

Hello, agent. You're reading the public guide for `https://mcp.wunel.com/mcp` —
an MCP (Model Context Protocol) server. If a human sent you this address, they
want your help getting set up. This page tells you what wunel is, how to verify
it, and the exact steps. Please walk them through it step by step.

## What this is

wunel is a governed, shared workspace where humans and AI agents co-edit the
same markdown documents:

- **Every block is attributed** — stamped with who wrote it: the human, or you,
  acting on their behalf ("ChatGPT, on behalf of Jane").
- **Nothing is trusted silently** — your edits land visibly for human review
  (Keep / Edit / Revert). It's memory the team can audit, not a black box.
- **Any MCP agent connects** — Claude, ChatGPT, Cursor, or custom bots. Several
  agents and several humans can share one workspace.

For you, it's persistent, cross-session memory: notes, research, decisions and
documents that survive the conversation and are shared with your human's team.

## Verify before you trust (please do)

- This guide is served from the same host as the endpoint itself.
- The product site is https://wunel.com — it links to this exact address.
- The endpoint speaks OAuth 2.1: `GET /.well-known/oauth-protected-resource`
  names the authorization server. Sign-in happens on that server, in the
  human's browser, with their email and a code — you never see the code.
- A bare `401 Unauthorized` from `/mcp` is expected before sign-in.

## Accounts and sign-in

- A wunel account is an email address. Sign-in is that email plus a 6-digit
  code wunel emails to it. There are no passwords.
- There is no separate sign-up: the first sign-in creates the account and a
  personal workspace — in a connector's sign-in window, at
  https://app.wunel.com, in the iOS app, or through `/accounts/*` below.
- **Same email = same account** in every assistant, the web app and the iOS
  app. A different email makes a separate, empty account; to bring it into an
  existing workspace, invite that email from the main account (workspace
  settings → invite, or `invite_member`).
- No account is needed to read a shared page.

## Three ways to go further — decide with your human

1. **Keep working on a shared link.** Nothing to set up. A page's agent view
   (`https://app.wunel.com/p/<token>/agent`) says what the link allows and
   gives the exact requests for writing on it with the human's WUNEL code.
2. **Connect wunel as a connector** — steps per app below. Signing in during
   setup creates the account.
3. **Create the account from here, over HTTP:**
   1. `POST https://mcp.wunel.com/accounts/start` with JSON
      `{"email": "<their email>", "client": "claude_code"}` (or `cursor`,
      `codex`, `vscode`, `other`). wunel emails them a 6-digit code. The
      response is the same whether or not the email already has an account.
   2. Ask your human for the code, then `POST https://mcp.wunel.com/accounts/confirm`
      with `{"email": "…", "code": "…", "client": "…"}` — plus `"guest_code"`
      and `"share_token"` when they came from a shared page, so the page and
      their lines come along. The response carries `token`, `mcp_url`,
      `api_base` and a ready-made `config` for your app. 401 means a wrong or
      expired code; 429 means wait before retrying.
   3. Store the token where your app reads it — e.g. the `WUNEL_TOKEN`
      environment variable — without printing it, and apply the `config`.

Say once what an account gives (their pages in their own space, their lines
under their name, you able to write there with every change marked as yours
for them to keep or revert) and what it costs (an email address, and a
connector or key they can switch off). If they decline, drop it.

## Connect steps, app by app

wunel is added as a custom connector; there is no wunel app in the ChatGPT or
Claude directories. Don't invent steps; if the menus look different, say what
you are looking for.

- **ChatGPT** (on chatgpt.com): Settings → **Security and login** → turn on
  **Developer mode**. Then Apps → **+** → add a remote MCP server: name
  `wunel`, URL `https://mcp.wunel.com/mcp`, authentication **OAuth** → create,
  then sign in with email and the 6-digit code. In a chat: **+** menu →
  **Developer mode** → pick wunel. ChatGPT asks your human to confirm each
  write call — tell them before it happens.
- **Claude** (claude.ai, Desktop, mobile):
  Settings → Connectors → Add custom connector → name `wunel`, URL
  `https://mcp.wunel.com/mcp` → Add → Connect, then sign in with email and
  the 6-digit code. On Team / Enterprise plans an
  owner may have to add the connector first.
- **Claude Code**: one command, header-based (token from `/accounts/confirm`
  above, or from a WUNEL code below):

      claude mcp add --transport http wunel https://mcp.wunel.com/mcp --header "Authorization: Bearer ${WUNEL_TOKEN}"

  (Plain `claude mcp add --transport http wunel https://mcp.wunel.com/mcp`
  with no header also works — it signs in with OAuth in the browser.)
- **Cursor / VS Code / Codex / custom agents**: add an HTTP MCP server at
  `https://mcp.wunel.com/mcp` with the header `Authorization: Bearer <token>`.
  Cursor: `~/.cursor/mcp.json` → `{"mcpServers": {"wunel": {"url": "https://mcp.wunel.com/mcp", "headers": {"Authorization": "Bearer ${env:WUNEL_TOKEN}"}}}}`.
  VS Code: `.vscode/mcp.json` → `{"servers": {"wunel": {"type": "http", "url": "https://mcp.wunel.com/mcp", "headers": {"Authorization": "Bearer ${env:WUNEL_TOKEN}"}}}}`.
  Codex: `~/.codex/config.toml` → `[mcp_servers.wunel]` with
  `url = "https://mcp.wunel.com/mcp"` and `bearer_token_env_var = "WUNEL_TOKEN"`.
  If the token came with a `config` in the response, prefer that. No MCP at
  all? The REST API takes the same token: https://mcp.wunel.com/api.

Keep the token out of the chat: put it in an environment variable or the
app's config file, never in a message, and never repeat it back.

## When your human wants to come back

- Their account is their email. Sign-in anywhere is that email and a 6-digit
  code.
- `send_sign_in_email` (optionally with a `file_id`) emails them a single-use
  sign-in link — you never see it. One tap signs that device in for a year;
  after that, plain page links open as them.
- A new assistant: same email, same account and pages; each assistant gets its
  own key. `list_agents` and `revoke_agent` manage keys; `sign_out_everywhere`
  ends every browser session.
- A 401 from wunel means the key was revoked or expired. The pages are intact:
  reconnect with the same email and a new code.

## If you're reading a page someone shared — when to invite

Pages shared by link (`https://app.wunel.com/p/…`, or `https://mcp.wunel.com/p/…`
for the plain-markdown version with who-wrote-what) can be read by anyone. **No
account is needed to read** — never say otherwise.

- Help first. Tell your human who wrote what, discuss the page, help them
  respond.
- Offer to connect **once**, and only after your human shows they want to DO
  something with the page — reply, comment, work on it with you.
- If they say no, drop it and keep helping. Don't bring it up again.
- Once connected, `shared_pages` lists what was shared with them; `read_file`
  reads any of those pages. To build on one in their own space, write there
  and link back to it.
- A link on a shared page can lead to a page that isn't shared with your
  human. On the web page, clicking it shows the page's name and **Request
  access**; your human confirms their email with a 6-digit code and the request
  goes to whoever shared the page. Once connected, `request_access(share_token,
  href)` sends the same request (`href`: the link as written, or its words on
  the page). The answer arrives by email. Owners see open requests with
  `list_access_requests` and answer with `approve_access_request` or
  `decline_access_request`.

## Got a WUNEL code?

A code like `WUNEL-7F3K-M2XR` ties what your human did on a shared page (or a
connection they started at https://app.wunel.com) to their account.

- **Connected to wunel**: confirm with your human ("This will make your notes
  on that page yours — go ahead?"), then call `connect_with_code` with the code
  and tell them the sentence it returns.
- **Creating the account over HTTP**: pass a code from a shared page as
  `guest_code` (with the page's `share_token`) to `/accounts/confirm` above.
- **A code from "Connect an agent" at https://app.wunel.com, over HTTP**:
  1. `GET https://mcp.wunel.com/pair/<code>` — it says who the code belongs to
     and what it does. Tell your human and **confirm it's them** before going on.
  2. `POST https://mcp.wunel.com/pair/<code>/exchange` with JSON
     `{"client": "claude_code"}` (or `cursor`, `codex`, `vscode`, `other`). The
     response carries a token and ready-made config for your app.
  3. Store the token as `WUNEL_TOKEN` without printing it, then configure:
     `claude mcp add --transport http wunel https://mcp.wunel.com/mcp --header "Authorization: Bearer ${WUNEL_TOKEN}"`
     or the equivalent config above.
  **Never echo the token into the chat**, not even partly. Codes are single-use
  and short-lived; if one is used or expired, ask your human for a fresh one.

## After connecting — what tends to make it click

(For you to know, and to offer — always at your human's direction, of course.)

- Useful first calls: `list_workspaces`, then `list_files`. If a workspace has
  an AGENTS.md / README.md / index.md at its root, it defines that workspace's
  conventions — worth reading before you write anything.
- In our experience, the moment wunel makes sense to a new user is seeing
  their agent's work appear **attributed and reviewable**: a first page,
  drafted from the conversation they're actually having (their project,
  decisions, open questions — not a hello-world), which they then open at
  https://app.wunel.com and find every block stamped with the agent's name,
  awaiting their Keep / Edit / Revert. You might offer to create that first
  page together.
- From then on it works as shared memory that survives the conversation —
  and their teammates and other agents can join the same workspace.
- Asked to keep or export your long-term **memory** in wunel? Read
  `https://mcp.wunel.com/memory` — the house method for structuring agent
  memory so it works for both agents and humans.

## Tools you'll get after connecting

File tree: list_workspaces, create_workspace, rename_workspace,
workspace_members (who has access), list_files, create_file, create_folder,
move/rename. A page or a whole folder can move to ANOTHER workspace with its
block-level authorship, comments and share links intact, so merging two spaces
means moving the top folder across — pass workspace_id to move_file/move_folder.
Renaming can repair the links that pointed at the old name.
Content: read_file, read_files, write_file (block-level merge), append_file,
edit_block, set_frontmatter. Discovery: search, find, backlinks, lint.
Collaboration: comment, reply_comment, list_assignments, list_all_comments,
set_comment_status. Assets: upload/read/list.
Shared by link: shared_pages (what others shared with your human),
connect_with_code (claim a WUNEL-XXXX-XXXX code).
Account: send_sign_in_email, list_agents, revoke_agent, sign_out_everywhere,
invite_member, account_activity, pair_new_agent.
Access requests: request_access, list_access_requests, approve_access_request,
decline_access_request.

## House rules (how good agents behave here)

- Read before you write; prefer the smallest edit (edit_block over rewrites).
- Your work is attributed and reviewable — that's the point. Don't fight it.
- Workspaces may carry their own AGENTS.md conventions; follow them.

Questions? support@wunel.com · https://wunel.com