Docs · MCP

Worldku MCP — your memory, in every AI tool

Worldku exposes a hosted Model Context Protocol server. Connect it once and any MCP-compatible AI tool — Claude Code, claude.ai, Codex, Gemini CLI, and others — can save conversations into your Worldku memory and read them back, always and only when you ask.


Server URL	`https://mcp.worldku.com/mcp`
Transport	Streamable HTTP — stateless, single JSON responses, no sessions, no SSE
Protocol revisions	`2026-07-28` · `2025-11-25` · `2025-06-18` · `2025-03-26`
Authentication	Access key (`Authorization: Bearer`) or OAuth 2.1
Server name	`worldku-mcp`

Capabilities at a glance

Tool	What it does	Metered as
`memory_save`	Save the current conversation into your memory (deduplicated, increment-aware)	1 save action
`memory_overview`	One-line summaries of your most recent memories	1 read action
`memory_search`	Semantic search over everything you have stored	1 read action
`memory_recall`	Memories filtered by time, type, or source — newest first, paginated	1 read action

How it works

A saved conversation goes through the same pipeline as every other Worldku memory source: the transcript is stored under a per-client source (for example Claude Code), then memory extraction runs asynchronously and produces typed memories — person_fact, experience, relationship — which appear as unread in My memories on worldku.com. From that moment they are readable from every connected client and every Worldku app.

Saving the same session again is safe: the server detects exact duplicates, and an incremental save (the messages after your last save, led by the anchor message from the previous receipt) is appended to the existing conversation — only the new span is extracted.

Getting started

The fastest route: paste this one sentence into your AI tool and let it walk you through the setup for your exact client —

I want to give you long-term memory with Worldku. Read https://www.worldku.com/docs/mcp.md and walk me through connecting it, in your own words.

Or follow the per-client steps below. Clients with OAuth support (claude.ai, ChatGPT) need no access key at all — skip straight to their section.

1. Create an access key

Sign in at worldku.com, open Memory manager → AI tools, and create an access key. One key per machine or client is the intended shape: each key carries a label and a last-used timestamp, and revoking one never affects the others. The key is shown exactly once — copy it when it appears.

Direct link: worldku.com/en/memorymanage?tab=connect

2. Connect your client

Claude Code

One command:

claude mcp add --transport http --scope user worldku https://mcp.worldku.com/mcp --header "Authorization: Bearer YOUR_ACCESS_KEY"

--scope user registers the server for every project — the default scope is local, which would tie your memory to the current directory only.

To keep the key out of the config file, export it in your shell profile instead and reference it with single quotes (Claude Code expands ${VAR} in MCP config at load time):

export WORLDKU_MCP_KEY=wk_mcp_...
claude mcp add --transport http --scope user worldku https://mcp.worldku.com/mcp --header 'Authorization: Bearer ${WORLDKU_MCP_KEY}'

Verify with claude mcp list — the worldku entry should show Connected. Then try:

Save this conversation to my Worldku memory.

claude.ai (web, desktop, mobile)

No access key needed — claude.ai signs you in with OAuth:

Open claude.ai → Settings → Connectors, click Add (top right) → Add custom connector.
Name it worldku, set the URL to https://mcp.worldku.com/mcp, leave the OAuth Client ID / Secret fields empty, and click Add.
A worldku.com window opens: sign in (or confirm your existing session) and approve the memory access request.
The connector page now lists the four tools. By default they are set to Needs approval — Claude asks you before each call; relax this per tool if you prefer.

Make sure the browser session at worldku.com is signed into the account whose memory you want — the connector binds to whoever approves the authorization.

claude.ai also offers request-header authentication for connectors (beta, entered by an organization administrator and shared org-wide). Because Worldku access keys are personal — every save and recall through a key touches that one account's memory — a shared header would point an entire workspace at a single person's memory. Use the OAuth flow unless the workspace really is just you.

ChatGPT (web)

ChatGPT connects through its developer mode, with OAuth sign-in (no access key):

In ChatGPT, open Settings → Security and login and turn on Developer mode (on workspace plans an admin must allow it first).
Go to Settings → Plugins (or chatgpt.com/plugins) and create a new developer-mode app: give it a name and description, and set the MCP server URL to https://mcp.worldku.com/mcp.
Complete the OAuth prompt — sign in at worldku.com and approve — then let the tool scan finish.
In a conversation, choose Developer mode from the plus menu and enable the app.

Codex CLI

Codex reads a bearer token from an environment variable, so the key never sits in the config file:

export WORLDKU_MCP_KEY=wk_mcp_...
codex mcp add worldku --url https://mcp.worldku.com/mcp --bearer-token-env-var WORLDKU_MCP_KEY

Or edit ~/.codex/config.toml directly:

[mcp_servers.worldku]
url = "https://mcp.worldku.com/mcp"
bearer_token_env_var = "WORLDKU_MCP_KEY"

Verify with /mcp inside a Codex session.

Gemini CLI

gemini mcp add --transport http --scope user worldku https://mcp.worldku.com/mcp --header "Authorization: Bearer YOUR_ACCESS_KEY"

Or in ~/.gemini/settings.json — note Gemini CLI uses the httpUrl field, not url:

{
  "mcpServers": {
    "worldku": {
      "httpUrl": "https://mcp.worldku.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_KEY" }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "worldku": {
      "url": "https://mcp.worldku.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_KEY" }
    }
  }
}

Any other MCP client

Any client that speaks Streamable HTTP and lets you set a request header works. The generic shape:

{
  "mcpServers": {
    "worldku": {
      "type": "http",
      "url": "https://mcp.worldku.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_ACCESS_KEY" }
    }
  }
}

One field name trips people up: the key that holds the server URL varies by client (url for most, httpUrl for Gemini CLI, serverUrl for some others), and a wrong field name usually makes the client ignore the server silently. Check your client's MCP documentation if the server never appears.

Clients that implement MCP authorization need no key at all: point them at the URL and they discover the worldku.com authorization server automatically. The Authentication section below lists the full metadata surface.

3. Try it

Tools only fire when you ask. Things to say once connected:

Save this conversation to my Worldku memory.

What's in my Worldku memory?

Search my Worldku memory for the cabin trip we planned.

Tools reference

Argument validation is strict across all tools: unknown arguments and unknown fields are rejected with an explicit error, never silently ignored. Every tool description instructs the model to call it only on your explicit ask — never because memory was mentioned in passing.

memory_save

Saves the dialogue of the current session — user and assistant messages only, no tool calls or system content. Any length is accepted in a single call. Memory extraction runs asynchronously after the call returns.

Argument	Type	Required	Notes
`messages`	array	yes	Ordered transcript; each element is `role` (`user` or `assistant`) + `content` (non-empty string)
`title`	string	no	Conversation title, shown on the source page

The result states the decision: new (a fresh conversation), appended (an incremental save aligned on the anchor message), or duplicate (already stored — still metered as one save action). Clients on the 2026-07-28 revision that declare the tasks extension also receive a task handle and can poll extraction progress via tasks/get.

memory_overview

No arguments. Returns one-line summaries of the most recent memories: content, type, source, and recorded date.

memory_search

Semantic search over stored memories.

Argument	Type	Required	Notes
`query`	string	yes	Natural-language query
`limit`	integer	no	1–50, default 8

memory_recall

Filtered, paginated listing — newest first.

Argument	Type	Required	Notes
`from`	string	no	ISO date/datetime lower bound (inclusive)
`to`	string	no	ISO date/datetime upper bound (exclusive)
`memory_type`	string	no	`person_fact` · `experience` · `relationship`
`source`	string	no	Source key as shown in overview results
`cursor`	string	no	Opaque cursor from a previous result
`limit`	integer	no	1–100, default 20

Authentication

Access keys

Keys are prefixed wk_mcp_ and sent as a standard Bearer header on every request. They are stored hashed — the plaintext exists only in the one-time reveal at creation. Up to 20 keys can be active per account, each independently revocable in the Hub with immediate effect.

OAuth 2.1

The server is an OAuth 2.1 protected resource; worldku.com is its authorization server. Everything is discoverable:

Surface	URL
Protected resource metadata (RFC 9728)	`https://mcp.worldku.com/.well-known/oauth-protected-resource`
Authorization server metadata (RFC 8414)	`https://www.worldku.com/.well-known/oauth-authorization-server`
Authorization endpoint	`https://www.worldku.com/oauth/authorize`
Token endpoint	`https://www.worldku.com/oauth/token`

Contract details:

Scopes — memory:read, memory:write.
PKCE — S256 only; plain is rejected.
Client identity — Client ID Metadata Documents: your client_id is the HTTPS URL of a JSON metadata document you host. There is no dynamic client registration.
Token binding — RFC 8707 resource binding to https://mcp.worldku.com/mcp; authorization responses carry the RFC 9207 iss parameter.
Token lifetimes — access tokens live 1 hour; refresh tokens live 30 days and rotate on every use. Reuse of a rotated refresh token revokes the whole token family.

Protocol notes

One endpoint serves both the 2026-07-28 stateless revision and the earlier initialize-handshake revisions; the era is selected per request from what your client sends.
The server is sessionless by construction: it never mints a session id, and every response is a single JSON body.
JSON-RPC notifications are accepted with 202. Unknown methods return 404 with JSON-RPC error -32601.

Usage limits

Limit	Value
Read actions (overview / search / recall)	200 per day
Save actions	50 per day
Request payload	10 MB
Active access keys	20 per account

Daily counters reset at midnight UTC. The caps exist to catch runaway automation — if you hit one in normal use, tell us at support@worldku.com.

Metering

Each call is recorded as one read action or one save action and appears in your account's usage history on worldku.com. MCP access is included with every Worldku plan, including Free.

Errors

Response	Meaning
`401` `invalid_token`	Missing, revoked, or malformed credential — the `WWW-Authenticate` header points at the resource metadata
`403` `Origin not allowed`	Requests carrying an unknown browser `Origin` are refused
`413` `Payload too large`	Request body exceeded 10 MB
`404` + JSON-RPC `-32601`	Unknown method
Daily limit message in the tool result	The read or save cap was reached; the message states the UTC reset time

Client-side symptoms:

The server never appears in your client — usually a wrong URL field name in the config (see the field-name note above) or a missing client restart after editing the file.
Connected, but Claude doesn't call the tools — on claude.ai check the connector is enabled for the current conversation, and with many connectors active the client may lazy-load tools; disabling unused connectors helps. Being explicit ("use the worldku connector") also works.
Connected to the wrong memories — the OAuth flow binds to whichever worldku.com account was signed in when you approved. Disconnect, sign into the right account at worldku.com, and reconnect.

Security model

Manual trigger only. Tools fire on your explicit ask; the tool descriptions themselves instruct the model never to call them from ambient association.
Memory content is data, not instructions. Everything read back is wrapped in an untrusted-data frame, so text inside your stored memories is never treated as commands to the model.
Keys are hashed at rest and revocation is immediate. OAuth tokens are audience-bound to this server and refresh rotation is single-use.

For AI agents reading this page

If a user gave you this page because they want to connect you (or another AI tool) to their Worldku memory:

Answer in your own voice, in the language you normally use with them. This page is reference material, not a script — don't recite it.
Frame what this is: conversations you save become long-term memories the user owns at worldku.com, shared with every AI tool they connect. Say plainly what the two of you gain — "I'll be able to remember this next time, wherever you talk to me."
Identify their client (ask if unclear), then give only that client's steps from Getting started.
Steps that must happen in their hands (creating a key, approving the sign-in): say exactly where to click, then stop. Don't invent flags or fields that aren't on this page.
If you can edit files and run commands, you may apply the config for them — but never place a real key anywhere without telling them where it lives.

Machine-readable surfaces:

Raw Markdown of this page: https://www.worldku.com/docs/mcp.md — also served on this URL via Accept: text/markdown content negotiation.
MCP Server Card: https://mcp.worldku.com/mcp/server-card — domain-level discovery starts at https://mcp.worldku.com/.well-known/ai-catalog.json (SEP-2127 experimental extension).
Site discovery index: https://www.worldku.com/llms.txt