Skip to main content
Glama
deenesjakoruzh
soluai-spa

solucortex-mcp

Official
by soluai-spa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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: Menhir

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

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.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax memories to return.
project_idNoProject UUID. If omitted, the session default applies, else the backend infers it from the API key.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description adds value beyond that by disclosing 'Does not consume OpenAI quota' and clarifying the GET operation has no semantic processing. No contradiction with annotations, and the extra cost/behavioral detail is genuinely useful for agent decision-making.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, each earning its place: the core action, the best use cases, and a cost-relevant detail. Information is front-loaded and there is no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with two optional parameters and an existing output schema, the description covers purpose, usage scenarios, and a notable behavioral trait (no quota consumption). Nothing critical is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters (limit, project_id) are fully documented in the schema with defaults and constraints. The description does not add parameter-level details, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'List the project's memories' and explicitly notes the non-semantic nature with 'without semantic search (GET /memories)' and gives concrete use cases. This differentiates it from the semantic-search siblings (solucortex_search, solucortex_recall) without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit use contexts: 'quick inspection/audit' and 'confirm a just-created memory was stored'. It also implies that semantic search is NOT this tool's function, steering agents toward siblings for that need. It does not name the sibling tools explicitly, so there is a small gap, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesDescribe the current task/module in natural language, e.g. 'implement API key rotation in the secrets module'. Used to semantically retrieve the most relevant memories.
project_idNoProject UUID. If omitted, the session default applies, else the backend infers it from the API key.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the readOnlyHint and openWorldHint annotations, the description adds valuable behavioral detail: it returns only approved/active memories, ranks by semantic similarity plus importance, and warns about OpenAI embeddings being slower with a 20 req/min limit. This gives the agent important expectations about latency and throttling without needing to discover it at runtime.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact: one sentence states the action and endpoint, one sentence gives usage timing and return value, and one sentence notes performance characteristics. Every sentence adds meaningful information and the most important usage guidance is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich input schema, annotations, and presence of an output schema, the description covers the essential operating context: when to call it, what it returns, how results are ranked, and its performance constraints. No critical missing information prevents an agent from selecting and invoking the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully documents both parameters (query and project_id) with clear descriptions, so the schema coverage is 100%. The tool description adds no extra parameter-level meaning beyond what the schema provides, which matches the baseline of 3 for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies a specific action ('Build living context for a task') and an endpoint ('POST /context/build'), and explains it returns approved, active memories ranked by similarity and importance. This is not a tautology and conveys the tool's read-oriented purpose, though it does not explicitly compare itself to sibling tools like solucortex_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear timing directive: 'Call this at the START of a task, before touching code.' It establishes the intended context of use effectively, but it does not provide explicit exclusion criteria or name alternatives for cases where this tool would not be appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYesMemory type. The backend validates the value. Canonical vocabulary: architecture, decision, risk, convention, bug_history, tech_debt, sensitive_module, learning, external_integration. (Older backends may use technical_decision, historical_bug, current_state, task_closure.) On HTTP 422, retry with the alternate vocabulary.
titleYesShort, clear title (~80 chars max).
contentYesFull content: what to remember, why it matters, where it applies and what it prevents. NEVER include real secrets (tokens, passwords, .env, credentials).
importanceNoPriority 1-10. Default 5. 6-7 high; 8-9 important decision/risk/convention; 10 critical.
project_idNoProject UUID. If omitted, the session default applies, else the backend infers it from the API key.

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given annotations already indicate this is a non-read, non-destructive, non-idempotent operation, the description adds valuable behavioral context: the memory is stored with status 'approved' and is traced, and a bearer API key is required. It also discloses the safe-handling policy for secrets, which goes beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four concise sentences with no filler. The core action is front-loaded, followed by when-to-use, behavioral context, and the security caveat. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a memory-creation tool: it covers action, trigger conditions, authentication, post-condition (approved/traced), and secret-handling policy. With an output schema present and comprehensive parameter schemas, nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining how to handle sensitive content in the `content` parameter: record location/type/severity and action taken with a redacted reference. This is practical guidance beyond the schema's 'NEVER include real secrets' note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Record a memory in SoluCortex (POST /memories)'. It clearly distinguishes this write operation from its siblings (list, recall, search) by naming the creation endpoint and memory domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to call the tool: 'Call when closing a task or making a relevant technical decision.' It does not mention exclusions or alternatives, but the sibling tools are clearly different operations, so the primary usage context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv1.0.0
    • Changedsolucortex_list_memories1 field changed
      • changedInput schema / properties / project_id / description
        Previous value: -"Project UUID. If omitted, uses SOLUCORTEX_PROJECT_ID."New value: +"Project UUID. If omitted, the session default applies, else the backend infers it from the API key."
    • Changedsolucortex_recall1 field changed
      • changedInput schema / properties / project_id / description
        Previous value: -"Project UUID. If omitted, uses SOLUCORTEX_PROJECT_ID."New value: +"Project UUID. If omitted, the session default applies, else the backend infers it from the API key."
    • Changedsolucortex_remember1 field changed
      • changedInput schema / properties / project_id / description
        Previous value: -"Project UUID. If omitted, uses SOLUCORTEX_PROJECT_ID."New value: +"Project UUID. If omitted, the session default applies, else the backend infers it from the API key."
    • Changedsolucortex_search1 field changed
      • changedInput schema / properties / project_id / description
        Previous value: -"Project UUID. If omitted, uses SOLUCORTEX_PROJECT_ID."New value: +"Project UUID. If omitted, the session default applies, else the backend infers it from the API key."
  2. 4 tool updatesv0.1.0
    • First observedsolucortex_list_memories
    • First observedsolucortex_recall
    • First observedsolucortex_remember
    • First observedsolucortex_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Menhir

    Archolith
    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.
    3
    Apache 2.0

  • Jatobá Brain

    Ey-luccas
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides persistent, multi-project memory for AI agents via MCP, enabling them to store and retrieve tasks, decisions, errors, checkpoints, and documentation while keeping context isolated by project.
    2
    MIT