neuroloom-mcp 0.1.0

MCP server that gives AI coding agents persistent memory via the Neuroloom API

neuroloom-mcp

MCP server that gives AI coding agents persistent memory via the Neuroloom knowledge graph API.

Install via pip

Requires Python 3.12+

pip install neuroloom-mcp
neuroloom-mcp install-plugin

Then restart Claude Code. The plugin and MCP server are configured together. Set your API key with /plugins configure neuroloom in Claude Code.

To upgrade:

pip install --upgrade neuroloom-mcp
neuroloom-mcp install-plugin --force

---

Hosted (Cloud) Connection

The Neuroloom MCP server is available as a hosted service — no local installation required.

Public endpoint: https://mcp.neuroloom.dev/mcp

Prerequisites

You need a Neuroloom API key. Create one at app.neuroloom.dev/settings/api-keys.

Claude Code

Create .mcp.json in your project root (the directory where you run Claude Code):

{
  "mcpServers": {
    "neuroloom": {
      "type": "http",
      "url": "https://mcp.neuroloom.dev/mcp",
      "headers": {
        "Authorization": "Bearer nl_your_api_key_here"
      }
    }
  }
}

Other MCP Clients

Any MCP client that supports HTTP (streamable HTTP) transport can connect using the url transport type and the Authorization header shown above.

Claude Desktop: Claude Desktop currently supports only the stdio transport. To use Neuroloom with Claude Desktop, follow the local stdio setup instructions below.

Verifying Your Connection

Check MCP server connectivity (unauthenticated):

curl https://mcp.neuroloom.dev/health

Expected response: {"status": "ok", "version": "0.1.0"} with HTTP 200.

Validate your API key against the Neuroloom API directly:

curl -H "Authorization: Token nl_your_api_key_here" https://api.neuroloom.dev/api/v1/workspaces/

HTTP 200 confirms the key is valid.

Note: MCP clients send Authorization: Bearer <key>; the Neuroloom API uses Authorization: Token <key>. The MCP server translates between the two schemes automatically.

Troubleshooting

Error	Cause	Fix
401 authentication_failed	API key is invalid or revoked	Create a new key at app.neuroloom.dev/settings/api-keys
503 upstream_unavailable	Neuroloom API is temporarily down	Retry after a moment
Connection refused	MCP client doesn't support url (streamable HTTP) transport	Check client docs; Claude Desktop only supports stdio
Connection timeout	Server unreachable or slow to respond	Check https://mcp.neuroloom.dev/health for availability
MCP client says it needs to complete an OAuth flow	Client is connecting to an older server version without the OAuth compatibility layer	Upgrade to the latest server version and retry

OAuth Compatibility Layer

The server implements GET /.well-known/oauth-protected-resource as specified by RFC 9728. Some MCP clients (including newer versions of Claude Code) probe this endpoint before connecting to determine whether they need to start an OAuth authorization flow.

The handler returns an empty authorization_servers array, which signals to the client that no OAuth flow is needed — authentication is handled via the Authorization: Bearer <key> header that operators and developers already configure.

The implementation lives in neuroloom_mcp/server.py (oauth_protected_resource_handler). The route is registered without authentication middleware so the discovery probe is always reachable, even before a valid API key is presented.

Local Development (stdio)

For local use or Claude Desktop, install and run the MCP server as a stdio process.

Requires uv (Python package manager).

cd mcp && uv sync

Required environment variables

Variable	Description
MEMORIES_API_TOKEN	API key generated from the Neuroloom dashboard
MEMORIES_WORKSPACE_ID	Workspace ID found under Settings > Workspaces
MEMORIES_API_URL	Neuroloom API URL (default: https://api.neuroloom.dev)

# MEMORIES_API_URL=https://api.neuroloom.dev  (default, override for local dev)
MEMORIES_API_TOKEN=your_api_key_here
MEMORIES_WORKSPACE_ID=your_workspace_id_here

Claude Code (stdio)

Add to your project's .mcp.json:

{
  "mcpServers": {
    "neuroloom": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/path/to/neuroloom/mcp", "run", "neuroloom-mcp"],
      "env": {
        "MEMORIES_API_TOKEN": "your_api_key_here",
        "MEMORIES_WORKSPACE_ID": "your_workspace_id_here"
      }
    }
  }
}

Replace /path/to/neuroloom/mcp with the absolute path to the mcp/ directory in your local clone.

Documentation

Full setup guide and configuration reference: https://neuroloom.dev/docs