PQC Memory MCP Server

This is an MCP server for VaelEngine: your editor or agent gets tools to search, save, and organize memory for one org bucket. It works with Cursor, Claude Code, VS Code, JetBrains Junie, Zed, and other MCP clients (stdio or HTTP).

Install

npx -y pqc-memory-mcp init

1. Pick the client and whether the config is project or user (global).
2. Enter API URL, API key, and bucket ID when prompted (see Prerequisites).
3. Cursor only: choose Y (default) to enable session hooks — copies bundled .cursor/rules, .cursor/hooks, merges hooks.json, and runs npm install in .cursor/hooks.
4. Restart the IDE or agent and confirm the MCP server appears (config uses npx -y pqc-memory-mcp unless you change it).

setup is an alias for init. The wizard merges into the right config file:

| Client | Project | User (global) | |--------|---------|----------------| | Cursor | <project>/.cursor/mcp.json | ~/.cursor/mcp.json | | Claude Code | <project>/.mcp.json | ~/.claude.json | | JetBrains Junie | <project>/.junie/mcp/mcp.json | ~/.junie/mcp/mcp.json |

This repo (pqc-mcp-server) is the source that produces the npm package pqc-memory-mcp. End users only need the command above. Maintainers: Maintainer guide. Zip / offline install: docs/standalone-distribution.md.

From a git clone (before publish): npm install && npm run build && node dist/cli.js init (or npm run init from repo root).

Do not commit MCP JSON that contains real API keys.

Cursor (optional): Run init from your project root and accept session hooks to install assets into .cursor/ automatically (or copy manually from node_modules/pqc-memory-mcp/.cursor/ after npm install). sessionStart uses node .cursor/hooks/session-start.mjs. See docs/standalone-distribution.md.

Features

• Semantic Search - Find memories by meaning, not just keywords
• Reflective Memory - Intelligent synthesis using AI to answer questions from your memory bank
• Knowledge Graph - Explore entities and relationships extracted from memories
• Outcome Tracking - Tag memories as success/failure to improve future recommendations
• Mental Models - Pre-computed knowledge summaries
• Strategies - Learned reasoning patterns from successful outcomes
• Conversation Summaries - Save important conversations for future reference

Prerequisites

1. VaelEngine running - The memory API will be available online at https://vaelengine.com, or locally
2. API Key - Create one via the VaelEngine dashboard or API
3. Bucket - Create a memory bucket in VaelEngine for this agent or team

Optional: add-mcp

add-mcp can register the server for several agents at once (npx add-mcp list-agents). You still need PQC_API_URL, PQC_API_KEY, and PQC_BUCKET_ID in env unless you use npx -y pqc-memory-mcp init afterward.

Package: pqc-memory-mcp on npm. Example:

npx add-mcp "npx -y pqc-memory-mcp" -a cursor -y --name pqc-memory

Local build (not on npm yet): after npm run generate:standalone, point at node /absolute/path/to/.../oss-bundle/pqc-memory-mcp/dist/index.js (or .../pqc-mcp-server/dist/index.js after npm run build) and set env in the generated config.

Manual config (stdio MCP) if you set up the host yourself—the exact file and JSON shape depend on the client (Cursor uses mcpServers; others use TOML or different keys). Conceptually you need command, args, and env:

{
  "mcpServers": {
    "pqc-memory": {
      "command": "npx",
      "args": ["-y", "pqc-memory-mcp"],
      "env": {
        "PQC_API_URL": "http://localhost:8081",
        "PQC_API_KEY": "your-api-key",
        "PQC_BUCKET_ID": "your-bucket-uuid"
      }
    }
  }
}

(Example shape compatible with Cursor-style mcp.json; translate for your tool’s docs.)

Restart the host after changing env, then call a memory tool to confirm it reaches VaelEngine. No npm: standalone bundle or clone and Setup. Maintainers: Maintainer guide.

Setup

1. Install Dependencies

git clone https://github.com/CascadiaTech/pqc-mcp-server.git
cd pqc-mcp-server
npm install

2. Build

npm run build

3. Configure your MCP client

Point the host at dist/index.js (stdio) with PQC_API_* env vars. Example for Cursor (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "pqc-memory": {
      "command": "node",
      "args": ["/path/to/pqc-mcp-server/dist/index.js"],
      "env": {
        "PQC_API_URL": "http://localhost:8081",
        "PQC_API_KEY": "your-api-key",
        "PQC_BUCKET_ID": "your-bucket-uuid"
      }
    }
  }
}

Other clients: use their documented MCP location and field names (often the same command / args / env idea).

4. Restart the client

Restart the IDE or agent (or reload MCP) so it picks up the new server.

Available Tools

| Tool | Description | |------|-------------| | memory_search | Semantic search across memories | | memory_reflect | Intelligent synthesis with sources | | memory_write | Save new memory | | memory_graph_entities | List known entities | | memory_graph_related | Find related entities | | memory_graph_memories | Find memories by entity | | memory_tag_outcome | Mark memory as success/failure | | memory_mental_models_list | List mental models | | memory_mental_model_get | Get mental model details | | memory_mental_model_create | Create new mental model | | memory_mental_model_refresh | Refresh mental model | | memory_strategies_list | List learned strategies | | memory_strategy_get | Get strategy details | | memory_save_summary | Save conversation summary | | memory_batch_write | Write multiple memories | | object_upload | Encrypted upload via managed Kyber key (POST .../keys/managed/{key_id}/objects) | | object_download | Decrypted download via managed key (GET .../objects/{object_id}) | | object_list | List org objects (GET /objects, optional bucket) | | object_get | Object metadata (GET /objects/{id}) |

See docs/mcp-org-object-storage.md for the API contract.

Usage examples

In any connected MCP client’s chat:

• "Search my memories for authentication patterns"
• "What do I know about this project's testing approach?"
• "Remember that I prefer TypeScript over JavaScript"
• "Save this conversation - we fixed the database migration issue"

Remote HTTP MCP (Streamable HTTP)

For clients that only support HTTP (e.g. Claude.ai custom connectors), run the second entrypoint. Each MCP request carries an Authorization: Bearer <access_token> header. The HTTP server calls pqc-api once per cached tenant window:

GET {PQC_TENANT_RESOLUTION_URL}/api/v1/mcp/tenant-context

Alignment with pqc-api (see docs/pqc-api-tenant-context-go.md):

| MCP env | Value | |--------|--------| | PQC_TENANT_RESOLUTION_URL | Public API origin only — no path, no trailing slash required, e.g. https://crypticpqc.com or http://localhost:8081. Same host you use for /api/v1/.... (Extra paths on this env are stripped to the origin.) | | Bearer token | With PQC_MCP_AUTH0_EXCHANGE unset: pqc-api access JWT only. With retry or always: Claude’s Auth0 access JWT is exchanged via POST /api/v1/auth/mcp-exchange, then tenant-context uses the minted VaelEngine API JWT (see docs/mcp-auth0-exchange-contract.md). |

After a 200, this server drives all memory traffic from the JSON body (api_url, api_key, bucket_id, optional session_ttl_minutes). It does not use PQC_API_URL / PQC_API_KEY / PQC_BUCKET_ID for HTTP mode (those remain for stdio and for PQC_TENANT_CONTEXT_MOCK only).

Optional service key (both sides must match):

| MCP | pqc-api | |-----|--------| | PQC_MCP_SERVICE_API_KEY | MCP_TENANT_SERVICE_API_KEY (same string) |

If set on pqc-api, MCP sends X-API-Key on tenant-context and mcp-exchange. If pqc-api does not require it, leave both unset (otherwise those routes return 401).

Build and start:

npm run build
export PQC_TENANT_RESOLUTION_URL="https://crypticpqc.com"
npm run start:http

Point the connector at POST https://your-mcp-host/mcp.

Health checks (for load balancers or clicking the host in a browser):

• GET https://your-mcp-host/ — short JSON + links
• GET /health or GET /healthz — minimal { "status": "ok", ... }
• GET /mcp — 200 JSON explaining that MCP uses POST (opening /mcp in a browser is not an error)

Optional OAuth discovery: set PQC_MCP_PUBLIC_URL and PQC_MCP_AUTHORIZATION_SERVERS (comma-separated issuer URLs) to expose RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource/mcp.

Cross-domain auth (Cryptic PQC): see docs/crypticpqc-cross-domain-auth.md for how crypticpqc.com, app.crypticpqc.com, mcp.crypticpqc.com, and crypto.crypticpqc.com should share Auth0, tokens, and tenant-context. When VaelEngine ships POST /api/v1/auth/mcp-exchange, see docs/mcp-auth0-exchange-contract.md for the request/response contract (MCP will call exchange, then tenant-context). Spec vs implementation: docs/mcp-authorization-spec-alignment.md.

Local dev without tenant-context: set PQC_TENANT_CONTEXT_MOCK=1 and the usual PQC_API_* env vars; any Bearer maps to that env tenant (ignored when NODE_ENV=production). HTTP MCP: mock is only allowed when NODE_ENV is development, test, or production (unset or other values exit at startup to avoid accidental bypass).

Maintainer guide: develop, regenerate, test, release

This section is for people working in pqc-mcp-server (this repo). End users install pqc-memory-mcp from npm or a release zip—they do not run these steps unless they clone.

What lives where

| Path | Role | |------|------| | src/, package.json (root) | Author changes here. Root is private: true — never npm publish from repo root. | | packaging/published-package.json | The published package name, version, bin, files, and runtime dependencies. Bump version here before each npm release. | | oss-bundle/pqc-memory-mcp/ | Generated tree: what you npm pack / npm publish and what the GitHub Action zips. Gitignored; recreated by generate:standalone. |

Day-to-day: change code, rebuild, regenerate

Run these commands from the pqc-mcp-server repo root, not from oss-bundle/pqc-memory-mcp or an extracted npm tarball. The published package ships dist/ pre-built; npm run build there only prints where to go (npm run build in the generator repo compiles src/).

1. git pull (if using git) and npm install.

2. Edit src/ (and packaging/published-package.json if metadata changes).

3. Typecheck and compile:

   npm run typecheck
   npm run build

4. Regenerate the standalone folder (copies fresh dist/, docs, manifest from packaging, etc.):

   npm run generate:standalone

   • Offline / skip lockfile refresh inside the bundle:
     npm run build && node scripts/generate-standalone.mjs --no-lock
   • One-off version override for the generated package.json:
     npm run build && node scripts/generate-standalone.mjs --version=1.2.3

5. Automated smoke test (what consumers get from the registry):

   npm run verify:pack

   This runs generate:standalone, then npm pack inside oss-bundle/pqc-memory-mcp, installs that .tgz in a temp project, and checks bins + missing-env error + stdio startup line.

Local testing (manual, like “install my own package”)

Tarball smoke from generator: npm install && npm run build && npm run generate:standalone → cd oss-bundle/pqc-memory-mcp && npm pack → in a consumer project npm install /path/to/pqc-memory-mcp-*.tgz → npx -y pqc-memory-mcp init (or npm run init from repo root). Do not rely on npm run init inside oss-bundle unless you mean the published package script.

A. Tarball install (mirrors npm)

cd oss-bundle/pqc-memory-mcp
npm pack
mkdir -p /tmp/pqc-smoke && cd /tmp/pqc-smoke
npm init -y
npm install /absolute/path/to/oss-bundle/pqc-memory-mcp/pqc-memory-mcp-x.y.z.tgz
export PQC_API_URL="https://your-api-origin"
export PQC_API_KEY="your-key"
export PQC_BUCKET_ID="your-bucket-uuid"
./node_modules/.bin/pqc-memory-mcp

Expect [pqc-memory] Server started (stdio) on stderr. Use Ctrl+C to stop.
export VAR=value must have no space around =.

B. Guided init wizard (from repo, before publish):

npm run init

(or npm run build && node dist/cli.js init) — picks Cursor / Claude Code / Junie and writes the right mcp.json.

C. Point Cursor at a local build

• After npm run build: command = node, args: ["/absolute/path/to/pqc-mcp-server/dist/cli.js"], plus env.
• Or after generate:standalone: use …/oss-bundle/pqc-memory-mcp/dist/cli.js.

Release: version, verify, publish, GitHub

1. Version — edit version in packaging/published-package.json (semantic versioning).

2. Verify from clean generation:

   npm run verify:pack

3. Dry-run the publish tarball (optional):

   npm run pack:publish

   Inspect oss-bundle/pqc-memory-mcp/pqc-memory-mcp-*.tgz.

4. Publish to npm (requires npm login / token and rights to the package name):

   npm run publish:npm

   Equivalent to:

   npm run generate:standalone
   cd oss-bundle/pqc-memory-mcp
   npm publish --access public

   Do not run npm publish in the repo root (it is private).

5. Git — commit, tag (e.g. v1.2.3 matching packaging/published-package.json), push. The OSS bundle workflow (.github/workflows/oss-bundle.yml) can build a zip on release; attach the artifact or pqc-memory-mcp-standalone.zip from CI as needed.

Dev commands (watch mode)

npm run dev          # stdio server, tsx watch
npm run dev:http     # HTTP entry, tsx watch

npm start (Zeabur, Railway, Docker)

• If PQC_TENANT_RESOLUTION_URL is set → runs HTTP MCP (dist/http.js).
• Otherwise → runs stdio MCP (dist/index.js, needs PQC_API_*).

Use npm run start:http or npm run start:stdio to force one mode regardless of env.

Environment Variables

Stdio (local MCP clients)

Local stdio transport: used by most editor and CLI integrations (e.g. Cursor, Claude Code, Codex, Junie, Zed—whatever your host supports).

| Variable | Required | Description | |----------|----------|-------------| | PQC_API_URL | Yes | VaelEngine API URL | | PQC_API_KEY | Yes | Your API key | | PQC_BUCKET_ID | Yes | Bucket UUID for memories | | PQC_SESSION_TTL | No | Session TTL in minutes (default: 1440) |

HTTP MCP

| Variable | Required | Description | |----------|----------|-------------| | PQC_TENANT_RESOLUTION_URL | Yes | pqc-api public origin only (e.g. https://crypticpqc.com) for GET /api/v1/mcp/tenant-context | | PQC_MCP_HTTP_PORT | No | Listen port (default: 8787) | | PQC_MCP_SERVICE_API_KEY | No | If set, sent as X-API-Key on tenant-context and mcp-exchange; must equal pqc-api MCP_TENANT_SERVICE_API_KEY when that is enabled | | PQC_MCP_AUTH0_EXCHANGE | No | retry / 1 / true = exchange on 401; always = always call mcp-exchange first for Auth0 JWT. See mcp-auth0-exchange-contract.md | | PQC_MCP_DEBUG | No | Set to 1 for JSON debug lines on stderr: HTTP hits, PRM, tenant-context, mcp-exchange, auth branches (no secrets; inbound token fingerprint only). Disable after troubleshooting. | | PQC_SESSION_TTL | No | Fallback if tenant-context 200 omits session_ttl_minutes (pqc-api often returns 1440) | | PQC_MCP_ALLOWED_HOSTS | No | Comma-separated Host allowlist (DNS rebinding protection) | | PQC_MCP_PUBLIC_URL | No | Public origin for OAuth PRM (e.g. https://mcp.example.com) | | PQC_MCP_AUTHORIZATION_SERVERS | No | Comma-separated issuer URLs (with PQC_MCP_PUBLIC_URL, serves PRM) | | PQC_MCP_PRM_RESOURCE | No | Override RFC 9728 resource in PRM (default {PUBLIC_URL}/mcp). Set to match Auth0 API Identifier if clients map resource → audience and you otherwise get opaque tokens. | | PQC_TENANT_CONTEXT_MOCK | No | Dev-only stdio/HTTP helper; with HTTP, NODE_ENV must be development, test, or production. Ignored when NODE_ENV=production. |

Architecture

MCP host (IDE, CLI agent, or HTTP connector)
    ↓ MCP (stdio or Streamable HTTP)
pqc-memory-mcp
    ↓ HTTP + session token
VaelEngine API
    ↓
PostgreSQL + Qdrant + Neo4j

Streamable HTTP uses the same tools; the HTTP entry resolves Bearer → tenant via VaelEngine before opening a memory session per cached tenant runtime.

The stdio server maintains a persistent session with VaelEngine for one configured bucket. The HTTP server caches TenantRuntime (client + session manager) per bearer hash with LRU eviction.