SoluCortex MCP

Official Model Context Protocol server for SoluCortex — living technical memory for AI agents.

Connect any MCP-compatible agent (Claude Code, Claude Desktop, Cursor, Codex, Cline, …) to your SoluCortex project so it can recall the decisions, conventions, risks and architecture that matter before it works, and remember what it learns when it's done.

Website: solucortex.ai · Setup guide: solucortex.ai/docs/mcp · Tools reference: solucortex.ai/docs/mcp-tools · PyPI: solucortex-mcp · MCP Registry: io.github.soluai-spa/solucortex-mcp

Tools

Governance by design: agents propose, humans govern. Agents can never change a memory's status, rewrite its metadata, or delete it — edits go back to pending and deletions only happen from the SoluCortex panel.

Requirements

• A SoluCortex account and a project API key (prefix scx_) — get it from your SoluCortex dashboard.
• One of: uv (recommended), Python ≥ 3.10, or Docker.

Configuration

stdio mode (default, local)

The server is configured entirely through environment variables:

HTTP mode (remote, multi-tenant)

Run with MCP_TRANSPORT=http (or --http) to serve Streamable HTTP on $PORT (default 8080) — the mode behind https://mcp.solucortex.ai. Credentials travel with each request and the environment is ignored:

GET /health (and /healthz locally; Cloud Run's frontend intercepts /healthz) responds without auth. The MCP endpoint is /mcp, runs stateless, and shares nothing between requests/tenants.

Never commit your API key. Keep it in your MCP client config's env block or a local .env (see .env.example).

Install

Remote (recommended — nothing to install)

The hosted server at https://mcp.solucortex.ai/mcp speaks Streamable HTTP; your key travels with each request:

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

Or in any client with remote MCP support:

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

Claude Code (local, stdio)

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

Claude Desktop / Cursor / Cline (JSON config)

Add to the client's MCP config (claude_desktop_config.json, Cursor mcp.json, etc.):

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

From a local clone

git clone https://github.com/soluai-spa/solucortex-mcp
cd solucortex-mcp
cp .env.example .env   # fill in your key
./run.sh               # loads .env, then runs via uv
# or, with SOLUCORTEX_* already exported: uv run solucortex-mcp

Docker

Prebuilt image on GHCR:

docker run --rm -i \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  ghcr.io/soluai-spa/solucortex-mcp:latest

Or build it yourself:

docker build -t solucortex-mcp .
docker run --rm -i \
  -e SOLUCORTEX_API_KEY=scx_xxx \
  -e SOLUCORTEX_PROJECT_ID=your-project-uuid \
  solucortex-mcp

The server speaks MCP over stdio, so clients launch it as a subprocess (-i keeps stdin open).

Development

uv sync
uv run solucortex-mcp            # run (stdio)
MCP_TRANSPORT=http uv run solucortex-mcp   # run (HTTP on :8080)
uv run pytest                    # test suite
npx @modelcontextprotocol/inspector uv run solucortex-mcp   # interactive test

Notes

• Memory type vocabulary: the canonical set is architecture, decision, risk, convention, bug_history, tech_debt, sensitive_module, learning, external_integration. Some backends accept an older set (technical_decision, historical_bug, current_state, task_closure). The server passes type through and surfaces HTTP 422 so you can retry with the other set.
• Never store real secrets in a memory. Record location, type, severity and action taken instead.

License

MIT — see LICENSE.