SoluCortex MCP

Servidor oficial de Model Context Protocol para SoluCortex — memoria técnica viva para agentes de IA.

Conecta cualquier agente compatible con MCP (Claude Code, Claude Desktop, Cursor, Codex, Cline, …) a tu proyecto de SoluCortex para que pueda recordar las decisiones, convenciones, riesgos y arquitectura que importan antes de trabajar, y memorizar lo que aprende al terminar.

Herramientas

Related MCP server: Muninn

Requisitos

• Una cuenta de SoluCortex y una clave de API de proyecto (prefijo scx_) — consíguela desde tu panel de SoluCortex.

• Uno de: uv (recomendado), Python ≥ 3.10 o Docker.

Configuración

Modo stdio (predeterminado, local)

El servidor se configura íntegramente mediante variables de entorno:

Modo HTTP (remoto, multiinquilino)

Ejecuta con MCP_TRANSPORT=http (o --http) para servir Streamable HTTP en $PORT (predeterminado 8080) — el modo que hay detrás de https://mcp.solucortex.ai. Las credenciales viajan con cada solicitud y el entorno se ignora:

GET /health (y /healthz localmente; el frontend de Cloud Run intercepta /healthz) responde sin autenticación. El endpoint de MCP es /mcp, se ejecuta sin estado y no comparte nada entre solicitudes/inquilinos.

Nunca hagas commit de tu clave de API. Mantenla en el bloque env de la configuración de tu cliente MCP o en un .env local (consulta .env.example).

Instalación

Remoto (recomendado — no hay nada que instalar)

El servidor alojado en https://mcp.solucortex.ai/mcp se comunica mediante Streamable HTTP; tu clave viaja con cada solicitud:

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

O en cualquier cliente con soporte MCP remoto:

{
  "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 --from git+https://github.com/soluai-spa/solucortex-mcp solucortex-mcp

(Una vez publicado en PyPI: sustituye el comando por uvx solucortex-mcp.)

Claude Desktop / Cursor / Cline (configuración JSON)

Añádelo a la configuración MCP del cliente (claude_desktop_config.json, mcp.json de Cursor, etc.):

{
  "mcpServers": {
    "solucortex": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/soluai-spa/solucortex-mcp", "solucortex-mcp"],
      "env": {
        "SOLUCORTEX_API_KEY": "scx_xxx",
        "SOLUCORTEX_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

Desde un clon local

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

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

El servidor se comunica mediante MCP a través de stdio, por lo que los clientes lo lanzan como subproceso (-i mantiene stdin abierto).

Desarrollo

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

Notas

• Vocabulario de type de memoria: el conjunto canónico es architecture, decision, risk, convention, bug_history, tech_debt, sensitive_module, learning, external_integration. Algunos backends aceptan un conjunto más antiguo (technical_decision, historical_bug, current_state, task_closure). El servidor transmite type tal cual y devuelve HTTP 422 para que puedas reintentar con el otro conjunto.

• Nunca almacenes secretos reales en una memoria. Registra en su lugar ubicación, tipo, gravedad y acción tomada.

Licencia

MIT — consulta LICENSE.