Skip to main content
Glama
solucortex-mcp

solucortex-mcp

Official

SoluCortex MCP

PyPI CI Python License: MIT

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

Tool

What it does

When to use

solucortex_recall

Builds living context for a task (ranked by semantic similarity + importance)

At the start of a task, before touching code

solucortex_search

Ad-hoc semantic search over the project's memories

Specific questions mid-task

solucortex_remember

Records a memory (stored approved + traced as an authorized agent)

At close, or on a relevant technical decision

solucortex_update_memory

Corrects an existing memory — the edit returns it to pending for human re-approval in the panel

When a memory is right in spirit but wrong in detail

solucortex_flag_memory

Flags a memory as outdated/incorrect with a reason; a human resolves it in the panel

When a memory should be reviewed, archived or deleted

solucortex_list_memories

Lists memories without semantic search

Quick inspection / audit

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.

Related MCP server: ContextForge

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:

Variable

Required

Description

SOLUCORTEX_API_KEY

✅

Project API key (scx_…)

SOLUCORTEX_PROJECT_ID

optional

Default project UUID; if omitted, the backend infers it from the API key

SOLUCORTEX_URL

optional

API base URL. Default https://solucortex.ai

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:

Header

Required

Description

Authorization: Bearer scx_…

✅

The caller's project API key (401 without it)

X-Solucortex-Project

optional

Default project UUID; if omitted, the backend infers it from the API key

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

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).

Instructions for your agent (AGENTS.md)

Once connected, give your agent the methodology too: copy templates/AGENTS.md into the root of your repo (it works as AGENTS.md or CLAUDE.md). The MCP handshake already carries these instructions — the file lets you version them alongside your code, extend them with your own conventions, and optionally enable the commented Claude Code hook recipe for guaranteed recall.

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.

Available Tools

4 tools
solucortex_list_memoriesA
Read-only
Inspect

List the project's memories without semantic search (GET /memories).

Useful for quick inspection/audit or to confirm a just-created memory was stored. Does not consume OpenAI quota.

Inputs: limit, project_id. Returns: object

solucortex_recallA
Read-only
Inspect

Build living context for a task (POST /context/build).

Call this at the START of a task, before touching code: returns approved, active memories (decisions, conventions, risks, sensitive modules, architecture) ranked by semantic similarity + importance. Uses OpenAI embeddings (slower, 20 req/min).

Inputs: query (required), project_id. Returns: object

solucortex_rememberAInspect

Record a memory in SoluCortex (POST /memories).

Call when closing a task or making a relevant technical decision. As an authorized agent (Bearer api_key), the memory is stored with status 'approved' and traced. Never store real secrets: if you find one, record location/type/severity and action taken, with a redacted reference.

Inputs: type (required), title (required), content (required), importance, +1 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation4/5

    Mostly distinct: recall and search both perform semantic retrieval, but their use cases are clearly separated (start-of-task context building vs. ad-hoc queries). list_memories and remember are unambiguously different. The overlap is minor and well-documented.

    Naming Consistency4/5

    All tools share the solucortex_ prefix and use lowercase snake_case, but the naming convention is mixed: recall, search, and remember are single verbs, while list_memories includes an object. Consistent enough to be predictable.

    Tool Count5/5

    Four tools cover the core memory interactions (list, recall, search, record) without unnecessary bloat. The count is well-scoped for a memory-oriented MCP server.

    Completeness3/5

    The set provides create and multiple read/search paths, but lacks update/delete or memory-status management. This creates a moderate lifecycle gap, though the primary agent workflows (build context, ask questions, record decisions) are covered.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides coding agents with governed semantic memory and code-graph context via MCP, enabling code-linked recall, blast-radius impact analysis, and lifecycle-aware memory management.
      799 PyPI
      3
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents and IDEs to capture conversations, extract structured knowledge into a queryable graph database, and recall past decisions, patterns, files, and errors across all projects and workspaces. Provides persistent memory tools for saving, searching, and cleaning up knowledge via MCP.
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to persistently remember, recall, and forget facts, preferences, and decisions through MCP, keeping project-scoped and personal memory available across sessions and clients.
      18 PyPI
      1
      MIT