solucortex-mcp
OfficialConnect any MCP-compatible agent to a SoluCortex project so it can recall living technical memory before a task and record learnings when done.
Recall task context (
solucortex_recall) — builds ranked, approved context (decisions, conventions, risks, sensitive modules, architecture) from a natural-language task description; call before touching code.Search memories semantically (
solucortex_search) — ad-hoc questions mid-task (e.g. "how is auth implemented?"), with an adjustablelimit(1–50).Record a memory (
solucortex_remember) — store type, title, content and importance 1–10; saved asapprovedand traced to the calling agent.List/inspect memories (
solucortex_list_memories) — plain listing without embeddings; useful for audits or confirming a write (no OpenAI quota used).Scope to a project — pass
project_idper call, or let the session default / backend API-key inference resolve it.Bring your own key — all calls act on the caller's
scx_project API key; secrets should never be stored, only redacted references with location/severity/action.Note on drift: the README also describes
solucortex_update_memoryandsolucortex_flag_memory(pending re-approval / human review workflow), but the current schema exposes only the four tools above.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@solucortex-mcp Before refactoring the payment module, recall relevant conventions and risks."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | What it does | When to use |
| Builds living context for a task (ranked by semantic similarity + importance) | At the start of a task, before touching code |
| Ad-hoc semantic search over the project's memories | Specific questions mid-task |
| Records a memory (stored | At close, or on a relevant technical decision |
| 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 |
| 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 |
| 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 |
| ✅ | Project API key ( |
| optional | Default project UUID; if omitted, the backend infers it from the API key |
| optional | API base URL. Default |
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 |
| ✅ | The caller's project API key (401 without it) |
| 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-mcpClaude 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-mcpDocker
Prebuilt image on GHCR:
docker run --rm -i \
-e SOLUCORTEX_API_KEY=scx_xxx \
ghcr.io/soluai-spa/solucortex-mcp:latestOr 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-mcpThe 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 testNotes
Memory
typevocabulary: the canonical set isarchitecture, 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 passestypethrough and surfacesHTTP 422so 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 toolssolucortex_list_memoriesARead-onlyInspect
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_recallARead-onlyInspect
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
solucortex_searchARead-onlyInspect
Ad-hoc semantic search of memories (POST /search/semantic).
Use for specific questions during a task (e.g. 'how is authentication implemented?'), distinct from recall which builds the full startup context. Uses OpenAI embeddings (20 req/min).
Inputs: query (required), limit, project_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Project memory, documentation and controlled secret access for AI coding agents.
Shared memory for connected AI tools. Projects, rules and skills over MCP. OAuth or API key.
Hosted long-term memory for AI agents via MCP. Recalld updates facts as information changes and retrieves relevant context. Connect with a Recalld EU account.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides 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 PyPI3Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables 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-
- AlicenseNot gradedqualityBmaintenanceEnables MCP-compatible AI agents to read and store architecture decisions, constraints, and research from a private Solveaux workspace, keeping generated code aligned with team-approved technical direction.338 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 PyPI1MIT