MCP setup

Connect your AI agent to your project's living memory. The SoluCortex MCP server lets Claude Code, Cursor and any MCP-compatible client recall your project's approved decisions before it works, and remember what it learns when it's done.

✅ Live and available now. The hosted MCP server is running in production at mcp.solucortex.ai, and the solucortex-mcp package is published on PyPI.

💡 Two ways to connect: the hosted server at mcp.solucortex.ai (recommended — nothing to install) or the local server as a stdio subprocess of your agent. Both expose the same four tools.

Requirements

A SoluCortex project and its API key (scx_…). The Project ID (UUID) is optional — the backend infers it from the key. See Quickstart.
Local option only: uv or Docker.

Option A — Remote (recommended)

The hosted server at https://mcp.solucortex.ai/mcp speaks Streamable HTTP. Your key travels with each request as a header — nothing runs on your machine.

Claude Code

bash

claude mcp add --transport http solucortex https://mcp.solucortex.ai/mcp \
  --header "Authorization: Bearer scx_your_key" \
  --header "X-Solucortex-Project: your-project-uuid"

Claude Desktop / Cursor / any client with remote MCP support

json

{
  "mcpServers": {
    "solucortex": {
      "type": "http",
      "url": "https://mcp.solucortex.ai/mcp",
      "headers": {
        "Authorization": "Bearer scx_your_key",
        "X-Solucortex-Project": "your-project-uuid"
      }
    }
  }
}

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer scx_…` — your project API key. Requests without it get `401`.
`X-Solucortex-Project`	Optional	Default project UUID. If omitted, the backend infers it from your API key. Can be overridden per tool call.

Option B — Local (stdio)

The same server, running on your machine as a subprocess of your agent. Open source (MIT) at github.com/soluai-spa/solucortex-mcp, published on PyPI.

Get the package

Three ways to install or run it — pick one:

bash

# A) uv — runs it without installing (recommended)
uvx solucortex-mcp

# B) pip — installs the `solucortex-mcp` command from PyPI
pip install solucortex-mcp

# C) from GitHub source — latest, or to work on it
pip install "git+https://github.com/soluai-spa/solucortex-mcp"
# ...or run it with uv straight from GitHub:
uvx --from "git+https://github.com/soluai-spa/solucortex-mcp" solucortex-mcp

💡 The client examples below use uvx. If you installed with pip (options B/C), replace the command with solucortex-mcp and drop the uvx args.

Claude Code

bash

claude mcp add solucortex \
  -e SOLUCORTEX_API_KEY=scx_your_key \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  -- uvx solucortex-mcp

Claude Desktop / Cursor / Cline

json

{
  "mcpServers": {
    "solucortex": {
      "command": "uvx",
      "args": ["solucortex-mcp"],
      "env": {
        "SOLUCORTEX_API_KEY": "scx_your_key",
        "SOLUCORTEX_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Environment variables (local mode)

Variable	Required	Description
`SOLUCORTEX_API_KEY`	Yes	Project API key (`scx_…`).
`SOLUCORTEX_PROJECT_ID`	Optional	Default project UUID. If omitted, the backend infers it from your API key. Can be overridden per tool call.
`SOLUCORTEX_URL`	Optional	API base URL. Defaults to `https://solucortex.ai`.

🔒 Never commit your API key. Keep it in the client's env/headers block or a local .env that is git-ignored.

Instructions for your agent (AGENTS.md)

The MCP handshake already teaches your agent the SoluCortex workflow, but you can also version it in your repo: a generic template that works as AGENTS.md or CLAUDE.md, with a placeholder for your own conventions and a commented Claude Code hook recipe for guaranteed recall. Download the full template from raw.githubusercontent.com/soluai-spa/solucortex-mcp/main/templates/AGENTS.md or copy the essentials below.

markdown

# SoluCortex — Agent Instructions

Full template: https://raw.githubusercontent.com/soluai-spa/solucortex-mcp/main/templates/AGENTS.md

1. START of a task: call solucortex_recall with the task description before touching
   code. Recall is a partial selection (top-N): if a type is cut, run a second,
   targeted query for it or declare "read N/M convention; context may be missing".
2. DURING: call solucortex_search for specific questions instead of re-deriving answers.
3. CLOSE: call solucortex_remember with one of the 9 types (architecture, decision,
   convention, risk, bug_history, tech_debt, sensitive_module, learning,
   external_integration) and importance 1-10 (8+ only for structural decisions/risks).
   A memory may be stored as pending until a human approves it — expected, do not retry.
4. CORRECTIONS: solucortex_update_memory sends the memory back to pending;
   solucortex_flag_memory marks it for review — in both cases tell the user to
   approve/resolve it in the SoluCortex panel. Deletion is human-only.

Never store secrets (tokens, passwords, .env values) in a memory.

💡 The file reinforces the workflow; it does not enforce it. For a hard guarantee that recall happens, enable the commented hook recipe included in the full template (Claude Code SessionStart / UserPromptSubmit hooks).

Verify the connection

In your agent, ask it to recall context for a task. It should call solucortex_recall and return your project's memories. If you get an authentication error, re-check the API key and Project ID. The hosted server also answers https://mcp.solucortex.ai/health with {"status": "ok"}.

✓ Connected. Your agent now starts each task with the approved context already in place — and can propose new memories when it closes. Next: the tools reference, or read the launch post.