Skip to main content
Glama
nexusm-mcp-server

nexusm-mcp-server

by 10CG

nexusm-mcp-server

Nexusm MCP Server — generic MCP server exposing Nexusm core capabilities (memory, conversation, knowledge, feedback, context) to MCP clients via @modelcontextprotocol/sdk stdio + Streamable HTTP transports.

Published to npm as @nexusm/mcp-server.

Tracked in Nexusm main repo: packages/nexusm-mcp-server (US-037 v7.0).

Configuration

Set via environment (e.g. the env block of your client's .mcp.json):

Env var

Required

Purpose

NEXUS_API_URL

yes

Base URL of the Nexus REST API. The server auto-appends /v1 if absent, so a bare origin (http://localhost:8787) or a local proxy URL works — you don't need to add the suffix manually. Canonical form: https://your-nexus-host/v1.

NEXUS_API_TOKEN

yes

Nexus API key (the product auth contract)

NEXUS_TENANT_ID

yes

Tenant id for the compound-id isolation

NEXUS_DEFAULT_USER_ID

no

Single-user pin. When set to a non-empty value, the server uses it as user_id for every tool call, overriding whatever user_id the LLM supplies. Leave unset for multi-user deployments where each tool call provides its own user_id. Recommended for personal / dogfood setups where the LLM picks inconsistent IDs across sessions. ⚠️ Do NOT set this on a shared / multi-user server — every user's memories and context would be written and retrieved under this single id, silently collapsing all users into one (cross-user memory bleed).

NEXUS_METRICS_PORT

no

Opt-in Prometheus /metrics port. Off by default in stdio mode — the scrape endpoint is a server-side concern, and a local stdio client (Claude Code / Cursor / Windsurf) has no scraper. Set this only when you actually scrape metrics. (NEXUS_MCP_TRANSPORT=http also enables it.)

The Nexus API auth contract is NEXUS_API_TOKEN. Any deployment-edge access control in front of the API (e.g. a reverse proxy / gateway / Cloudflare Access) is not this client's concern — handle it transparently at the network/transport layer (point NEXUS_API_URL at a local proxy) so the client stays deployment-agnostic. When pointing at a local proxy, set NEXUS_API_URL to the proxy origin (e.g. http://localhost:8787); the server will append /v1 automatically and log a one-line diagnostic to stderr confirming the normalization.

Related MCP server: synapse-mcp

Status

Wave 2 done (2026-05-22): 4 tools fully wired to @nexusm/sdk (context_retrieve / memory_search / memory_create / memory_feedback) + full §M-3 HTTP→MCP error mapping (mapHttpStatusToMcpError + 2 new error codes Unauthorized/RateLimited) + Prometheus metrics with cardinality guard + cross-substory + E2E + schema_sync integration tests. Correction (2026-09-12, issue #32): that mapping only recognised axios-shaped errors, which @nexusm/sdk never throws, so until the mapSdkErrorToMcpError bridge landed every SDK failure reached clients as InternalError (-32603); an auth edge / proxy answering instead of Nexus (SDK 5.2.0 UpstreamInterceptError) now maps to Unauthorized (-32011) with data.upstream_intercept: true — see CHANGELOG [Unreleased]. Wave 3 (nexus-claude-plugin Anthropic marketplace) pending — see proposal.

Known Wave 2 limitations: (1) CI red until Gate-1 — @nexusm/sdk@1.3.0 npm publish pending (user action; SDK rename merged at 1fbdd69 in nexus-sdk-js main); (2) integration tests env-gated (require NEXUS_TEST_API_URL/TOKEN/TENANT_ID Forgejo secrets, currently dormant); (3) Python backend mcp.py metrics defined but emit-site wiring deferred to Wave 3 (FU-MCP-BACKEND-EMIT-WIRING); (4) HTTP transport per-request server.connect() is scaffold-only — Wave 3 entry condition (FU-MCP-HTTP-SESSION) before plugin TASK-019 E2E runs.

Available Tools

4 tools
nexus.context_retrieveA

Use when user asks anything that might need context from prior sessions, prior conversations, or stored facts. Single call returns relevant memories, recent conversation turns, and knowledge entities together. Prefer this over nexus.memory_search when query is open-ended.

Inputs: user_id (required), query (required), limit, as_of. Returns: retrieve_id, memories, conversation_turns, knowledge_entities, +2 more

nexus.memory_createA

Persist a new memory. Use when user explicitly asks to 'remember X' or when storing structured facts (preferences, decisions, code snippets with language tag). Set memory_type to 'episodic' for events, 'semantic' for facts, 'procedural' for how-tos.

Inputs: user_id (required), content (required), memory_type, metadata, +3 more. Returns: memory_id, created_at, conflict_resolution

nexus.memory_feedbackA

Submit per-memory feedback on a previous nexus.context_retrieve call. Pass retrieve_id from earlier output. Rating 1-5, plus per-memory useful flag with optional reason. v5 feedback loop drives quality_score reranking.

Inputs: user_id (required), retrieve_id (required), rating (required), item_feedback, +2 more. Returns: feedback_id, retrieve_id, status, created_at

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: context_retrieve for broad context, memory_create for storing, memory_feedback for feedback, memory_search for targeted search. No overlap.

    Naming Consistency4/5

    All tools follow nexus_verb_noun pattern with snake_case. Slight inconsistency: two use 'memory_' prefix, one uses 'context_', but this reflects functional difference.

    Tool Count5/5

    Four tools cover core memory operations perfectly: creation, two retrieval modes, and feedback. No redundancy, each tool earns its place.

    Completeness3/5

    CRUD surface is incomplete: update and delete for memories are missing. Feedback partially addresses quality improvement, but lifecycle management has gaps.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers