MCP server

jnh mcp runs a Model Context Protocol (MCP) server that exposes an agent workspace's memory over stdio. Compatible MCP hosts, such as Claude Code, Claude Desktop, and Cursor, can access persistent agent memory through standard MCP tool calls.

The server exposes three tools:

recall_memory: Retrieves passages relevant to a query, plus a bounded snapshot of the workspace's knowledge graph.
remember_conversation: Submits conversation turns for asynchronous fact extraction and reconciliation.
formation_outcome: Queries the status and results of a submitted formation job.

Installation

The MCP server is built into the jnh CLI binary. No separate installation is required if jnh is installed:

jnh version

To install the CLI, see Getting started, then sign in or generate an API key.

Host environment and reachability

MCP hosts launch servers as local subprocesses communicating over stdio. Because the server runs locally, reachability is limited to processes running on the same machine:

Supported hosts	Unsupported hosts
Local desktop and editor agents (Claude Code, Claude Desktop, Cursor)	Browser-based interfaces (such as claude.ai)
Local scripts and command-line processes	Remote or hosted agent platforms
	Remote server deployments

For remote hosts and server-to-server integrations, use the Python, TypeScript, or Go SDK or the HTTP API (/v1) directly.

Host configuration

MCP hosts configure servers using a command, arguments, and environment variables. Specify the target workspace via the --workspace flag:

{
  "mcpServers": {
    "jennah": {
      "command": "jnh",
      "args": ["mcp", "--workspace", "my.agent"],
      "env": { "JENNAH_API_KEY": "jennah_sk_..." }
    }
  }
}

Alternatively, set the workspace using the JENNAH_MCP_WORKSPACE environment variable:

{
  "mcpServers": {
    "jennah": {
      "command": "jnh",
      "args": ["mcp"],
      "env": {
        "JENNAH_MCP_WORKSPACE": "my.agent",
        "JENNAH_API_KEY": "jennah_sk_..."
      }
    }
  }
}

To use an existing authenticated session instead of an API key, omit JENNAH_API_KEY and run jnh login. The MCP server reads and automatically renews the stored session tokens.

Ensure the workspace exists before starting the server:

jnh agents create my.agent

Workspace isolation and pinning

The workspace is pinned at server startup and cannot be overridden by tool parameters. Tools do not accept parameters for workspaces, scopes, agents, or tenants, preventing prompt injection attacks from redirecting operations to unintended workspaces.

Key operational characteristics:

A workspace is required at startup. The server exits immediately with no workspace is pinned if no workspace is configured.
Fail-fast authentication and authorization. If the provided credential cannot access the pinned workspace, the server fails during startup and logs an error, rather than failing during later tool invocations.
Single workspace per server process. Each server process handles exactly one workspace. To interact with multiple workspaces, configure multiple server entries in your MCP host.

Access control policies remain enforced server-side. The MCP server cannot access resources outside the permissions and selectors of its underlying credential.

Tools

`recall_memory`

Retrieves the remembered passages that semantically match a query, most relevant first, together with a bounded snapshot of the workspace's knowledge graph assertions (entities and relationships). The graph snapshot is not filtered by the query: it covers up to 50 nodes and 50 edges of the workspace.

Argument	Description
`query`	What to recall, as a question or topic (required)
`limit`	Maximum passages to return (default 10)

If nothing has been remembered yet, the tool returns an empty result without error.

Retrieved assertions include a qualified boolean flag. When false, the underlying assertion does not have verified currency (see temporal memory) and should not be treated as an active fact. The tool response includes explanatory notes when unqualified assertions are present.

`remember_conversation`

Submits conversation turns for asynchronous formation, including entity extraction, contradiction detection, and supersession reconciliation.

Argument	Description
`turns`	The conversation, in order: a list of `{role, content}` objects, where `role` is `user`, `assistant`, `system`, or `tool`

Because formation involves model inference and background processing, the call returns immediately upon acceptance with a job handle. Background processing continues independently of tool call timeouts or client cancellations.

Formation handles are deterministically derived from the submitted conversation content. Submitting duplicate conversations or retrying after network errors resolves to the same background task and does not create duplicate memories.

`formation_outcome`

Checks the processing status and results of a formation job handle returned by remember_conversation. It takes one argument, handle.

The response reports a status, candidate decisions (new, revised, already_known, rejected), and write counts. The status is one of:

running: formation is still in progress.
finished: formation completed and its results are reported.
nothing_written: the conversation established nothing new to remember.
unknown_handle: this server process did not submit the handle (see below).

Handles are tracked in-memory by the active server process. If the server restarts while a task is running, subsequent queries for that handle return unknown_handle. Completed data remains safely written to the workspace and can be queried via recall_memory. Resubmitting the conversation returns the same deterministic handle and resumes tracking.

Protocol and standard I/O

jnh mcp communicates using newline-delimited JSON-RPC over standard input and output. All operational logs, diagnostics, and errors are written to standard error.

Because standard output is reserved for protocol frames, the command rejects explicit output formatting flags such as -o json or --output json:

$ jnh mcp --workspace my.agent -o json
error: jnh mcp writes a protocol on standard output,
       so --output json cannot be honoured
hint: drop --output here;
      this command has no result to render in any format

If the JENNAH_OUTPUT environment variable is defined in the shell, jnh mcp ignores it rather than returning an error.

Troubleshooting

Server exits immediately

Check the host's server log (stderr). Common causes include:

Missing workspace: Ensure --workspace <name> or JENNAH_MCP_WORKSPACE is set.
Workspace unreachable: Verify that the workspace exists and the active API key or user session has permissions to access it.
Unauthenticated session: Run jnh login or provide a valid JENNAH_API_KEY.

Session disconnects during handshake

If the host disconnects immediately without an error dialogue, check stderr for a protocol version mismatch:

jnh mcp: the host asked for MCP protocol version
  "2019-01-01", which this server does not implement.
jnh mcp: this server implements 2026-07-28, 2025-11-25,
  2025-06-18, 2025-03-26, 2024-11-05.
jnh mcp: answered with "2025-11-25", because the
  lifecycle specification requires an answer here
  rather than a refusal.
jnh mcp: the host disconnects if it cannot speak that.
  If this session ends now, that is why.

The MCP lifecycle specification requires the server to negotiate by returning a supported version; the host terminates the connection if it cannot support that version. Update the host application or jnh to resolve protocol incompatibilities.

Tool calls denied

If tool calls return authorization errors, the API key or role lacks required permissions or its resource selectors do not cover the workspace. Authorization failures return explicit tool errors rather than empty results. Check assigned roles with jnh team roles or review your API key configuration.

Model does not invoke tools

Verify in the MCP host's settings that the server is active and connected. If the server is connected, tool invocation frequency depends on the host's system instructions and prompt configuration.