MemoryNode MCP server

**MCP to build.** Use MCP in Cursor, Claude Desktop, or agent IDEs while prototyping. **SDK/API to ship** in production — `POST /v1/memories` and `POST /v1/context` (see [Two-call integration](./TWO_CALL_INTEGRATION.md)). **MCP is for building in Cursor and Claude. SDK/API is for shipping production apps.** Same memory, same API key.

MemoryNode exposes two MCP surfaces:

Hosted MCP — Streamable HTTP JSON-RPC at POST /v1/mcp and POST /mcp (https://mcp.memorynode.ai/mcp or https://api.memorynode.ai/v1/mcp)
stdio MCP — local binary memorynode-mcp from @memorynodeai/mcp-server

Both call the same REST backend (/v1/memories, /v1/search, /v1/context, …) and enforce the same quota, plan, and rate-limit rules as direct REST.

When to use REST vs MCP

Use case	Choose
Production SaaS backend (chat, copilot, workflows)	REST or `@memorynodeai/sdk` — two-call remember → recall
Cursor, Claude Desktop, local agent editors	Hosted MCP or stdio MCP
Explicit schemas, idempotency keys, server-side retries	REST first
Billing and usage in production	REST or console — not MCP

MCP must not replace the two-call REST flow in product docs, quickstarts, or console onboarding.

Safe MCP for builders

Use MCP when a builder tool (Cursor, Claude Desktop, agent IDE) needs memory — not as your production SaaS backend.

Step	Action
1	Prove REST/SDK in Playground first
2	Configure stdio or hosted MCP (Integration recipes)
3	Call `context` before the agent answers
4	Call `memory` only for durable, user-confirmed facts

Policy defaults deny unsafe writes; see Policy below. Full agent recipe: Integration recipes — MCP for builders.

Policy (single source)

Hosted and stdio MCP both use McpPolicyEngine from @memorynodeai/shared (packages/shared/src/mcpPolicy.ts).

Policy contract version: MCP_POLICY_VERSION (currently 2026-04-19.1; see SUPPORTED_MCP_POLICY_VERSIONS).
Hosted MCP negotiates via optional request header x-mcp-policy-version (comma-separated client list).
Tool denials return stable action_id, policy_version, and error codes — same engine for stdio and hosted.
Implementation packages: @memorynodeai/mcp-core (hosted tool registry), @memorynodeai/mcp-server (stdio adapter). There is no separate forked policy for stdio vs hosted.

Production configuration

Variable	Production	Purpose
`MCP_INTERNAL_SECRET`	Required (secret)	Authenticates hosted MCP internal `fetch` to `/v1/*`; never expose to browsers
`MCP_ADVANCED_TOOLS_ENABLED`	Optional	Extended hosted tools are not registered in v1
`MEMORYNODE_REST_ORIGIN`	Optional	REST origin for MCP worker subrequests (default `https://api.memorynode.ai` on `mcp.memorynode.ai`)
`MCP_AUDIT_LOG_REQUIRES_TEAM`	Optional	Operator-only; extended hosted tools are not registered in v1
`MCP_CONNECTOR_SETTINGS_REQUIRES_TEAM`	Optional	Operator-only; not part of the public MCP catalog
`MCP_SESSION_DO`	Binding (Wrangler)	Durable Object for session registry metadata; transport may still be in-process per isolate

MCP_ADVANCED_TOOLS_ENABLED is not set in apps/api/wrangler.toml production [vars]. Enable only deliberately for operator workflows.

Hosted MCP

Endpoints

Method	Path	Purpose
`POST`	`/v1/mcp`, `/mcp`	JSON-RPC request (`initialize`, `tools/list`, `tools/call`)
`GET`	`/v1/mcp`, `/mcp`	Browser landing or SSE subscription
`DELETE`	`/v1/mcp`, `/mcp`	Close session

Authentication uses the same API key as REST (Authorization: Bearer <key> or x-api-key).

Default activation tools (always on)

P1 / activation tools are registered without MCP_ADVANCED_TOOLS_ENABLED:

Tool	REST equivalent	Purpose
`memory` / `memory_save`	`POST /v1/memories`	Store durable memory
`memory_list`	`GET /v1/memories`	List memories for scope
`memory_forget`	(policy-gated)	Request forget / archive flow
`memory_forget_confirm`	(policy-gated)	Confirm forget after policy check
`recall` / `search`	`POST /v1/search`	Retrieve relevant memories
`context` / `context_pack`	`POST /v1/context`	Prompt-ready context pack
`whoAmI` / `identity_get`	scope resolution	Inspect workspace and owner scope

Canonical v1 names: memory_save, memory_list, memory_forget, memory_forget_confirm, search, context_pack, identity_get (see HOSTED_V1_PUBLIC_TOOL_NAMES in @memorynodeai/mcp-core).

Use the same owner_id / user_id as REST. Omitting owner fields resolves to default-user (demos only).

Advanced tools (not in v1)

Extended hosted tools beyond the seven public tools are not registered in the current Worker build. Use REST or the console for billing and usage.

Session lifecycle and 409 handoff

Hosted MCP uses an in-process transport per Worker isolate plus a Durable Object session registry. Clients should send mcp-session-id after initialize.

HTTP	Meaning	Client action
409	Session exists in registry but transport is on another isolate (`mcp_session_handoff_required`)	Reinitialize: `DELETE` optional, then `initialize` again, store new `mcp-session-id`, retry pending `tools/call`
404	Unknown session (`not_found`) or idle TTL exceeded (`expired`)	Reinitialize MCP session; do not reuse old session id
401	API key mismatch for session	Fix key; reinitialize with correct key

409 response shape (JSON-RPC envelope, HTTP 409):

{
  "jsonrpc": "2.0",
  "error": { "code": -32000, "message": "Session transport unavailable on this isolate. Reinitialize MCP session." },
  "id": null
}

Safe retry pattern after 409 or 404:

Drop the stored mcp-session-id.
Send JSON-RPC initialize (same API key and protocol version).
Read the new mcp-session-id from response headers.
Retry tools/list / tools/call — use idempotent writes (request_id on REST-backed saves where applicable).

Cross-isolate routing is expected on Cloudflare Workers; re-init is the supported recovery — not a Durable Object transport upgrade in the current release.

Safety notes

Hosted MCP goes through policy checks and rate limits identical to REST.
Trial write gates match REST behavior.
Responses include x-request-id for support.
Advanced billing, audit, and connector tools are opt-in only.

stdio MCP

Install

npm install -g @memorynodeai/mcp-server
memorynode-mcp

Required environment

Variable	Required	Purpose
`MEMORYNODE_API_KEY`	yes	Bearer key for REST calls
`MEMORYNODE_BASE_URL`	yes	REST API base URL, e.g. `https://api.memorynode.ai`
`MEMORYNODE_USER_ID`	no	Default owner id for tool calls
`MEMORYNODE_NAMESPACE`	no	Default namespace
`MEMORYNODE_TIMEOUT_MS`	no	Per-request timeout

Tool surface

The stdio binary keeps the tool set intentionally small:

recall
context
memory
whoAmI

Legacy aliases such as memory_search, memory_context, and memory_insert are removed; use canonical tools only.

Upstream constraints

top_k is capped at 10 for recall / search
containerTag is capped at 128 chars
Policy can deny unsafe repetition or forbidden scopes
REST remains the canonical integration surface for app backends

For package layout, see packages/mcp-server/README.md. For HTTP facts, see docs/external/API_USAGE.md. For deploy secrets, see docs/internal/DEPLOYMENT.md.