Synap MCP Server

synap-mcp-server

Servidor MCP remoto alojado (HTTP Streamable) que re-expone las operaciones REST públicas existentes de Synap como herramientas MCP, de modo que las plataformas sin código (Gumloop, n8n) puedan dar a sus agentes memoria persistente con solo pegar una URL MCP y un token Bearer.

Es un adaptador sin estado — sin nuevo backend, almacenamiento ni pipeline. Cada llamada a herramienta se asigna a una operación REST existente, y el token Bearer synap_<key> entrante se reenvía textualmente a synap-cloud, que es quien gestiona la autenticación.

• Endpoint público (prod): https://synap-mcp.maximem.ai/mcp
• Salud: https://synap-mcp.maximem.ai/health

Herramientas

Herramienta	Operación REST	Notas
log_exchange	POST /api/v1/memories/create (mode=long-range)	Reenviar en cada turno; la extracción decide qué se persiste. user_id limita por usuario final, customer_id es solo B2B (ver Alcance); conversation_id opcional.
recall_context	POST /v1/context/{client|user|customer}/fetch (mode=fast)	Ruta crítica; sin IDs ⇒ alcance de cliente. El alcance customer es solo B2B.
list_recent_memories	/v1/context/.../fetch amplio (sin consulta)	Depuración / "prueba mi memoria". Mismas reglas de alcance.
check_memory_status	GET /api/v1/memories/status/{id}	No recibe IDs de alcance: el ingestion_id ya identifica la escritura.

Alcance: un contrato, dos modos

La API REST lo impone. No es un consejo, y está en producción desde el 2026-08-26 07:07 UTC.

Modo de instancia (user_context_isolation)	Qué enviar	Qué ocurre de lo contrario
equals_customer (B2C)	user_id y nada más. El id de usuario es toda la identidad.	Cualquier customer_id se rechaza con HTTP 400. /v1/context/customer/fetch no está disponible en absoluto.
strict (B2B)	customer_id es obligatorio, junto con user_id.	Un user_id por sí solo es un error. Sin cambios por este contrato.

GET /api/v1/auth/whoami informa el modo como user_context_isolation. Este servidor lo lee una vez por token y rechaza un customer_id localmente en una instancia B2C, de modo que un modelo recibe una frase que le indica qué enviar en lugar de un código de estado que no puede interpretar. Si el modo no puede leerse, no se rechaza nada y la API sigue siendo la autoridad.

No pasar ningún ID ⇒ alcance de cliente (compartido por credencial), válido en ambos modos. Nota: las escrituras con alcance de cliente no aparecen en la página de Memorias del panel (relacional), por lo que se recomienda el alcance por usuario cuando la visibilidad en el panel importa. Rellena user_id desde una expresión de n8n / entrada de Gumloop, y pasa el mismo valor en log_exchange y recall_context para que las escrituras y lecturas se dirijan a la misma persona.

Cabecera Host. El servidor desactiva la comprobación de rebote DNS del transporte MCP (está detrás de un proxy + autenticación Bearer), de modo que cualquier proxy inverso puede reenviar el Host real — sin necesidad de reescribir el Host.

Ejecutar localmente

pip install -e ".[dev]"
SYNAP_API_URL=http://localhost:8000 uvicorn synap_mcp_server.server:app --port 8090
curl http://localhost:8090/health        # {"status":"ok",...}

Informar el turno al agente de anticipación

Un servidor MCP no es un agente. Expone herramientas al agente de otra persona y recibe una llamada HTTP sin estado a la vez, por lo que la mayor parte de lo que hace un agente es invisible aquí: las llamadas a herramientas del llamador, sus resultados y su razonamiento nunca llegan a este proceso, y nada le dice a un servidor sin estado que una conversación ha terminado. Esos no se informan, porque no hay nada que informar.

El turno sí existe. log_exchange recibe el mensaje del usuario y la respuesta del asistente como argumentos. Establece MCP_STREAM_EVENTS=true y cada intercambio registrado también se informa como turno de conversación en POST /v1/events/batch, la puerta HTTP hacia la misma ruta de escucha que alimenta el stream gRPC, de modo que el agente de anticipación ve el turno y no solo la memoria extraída de él. No hay stream gRPC aquí para usar: este servidor no tiene SDK, no guarda estado entre peticiones, y cada petición puede llevar la clave de un inquilino distinto.

Está desactivado por defecto, a propósito. Activarlo añade una segunda llamada al backend por log_exchange, escribe el turno en el historial de conversación además del documento de largo alcance, y ejecuta el agente de anticipación, que factura llamadas de modelo.

Lo que no cambia en ningún caso: log_exchange sigue poniendo en cola el documento de largo alcance y sigue devolviendo el ingestion_id sobre el que se construyen check_memory_status y wait_for_processing. Un informe de turno es de mejor esfuerzo y nunca puede alterar lo que responde una herramienta. Un turno sin user_id o sin conversation_id no se informa en absoluto, porque la ruta de eventos requiere ambos.

Pruebas

pip install -e ".[dev]"
pytest -q

Configuración (env)

Var	Por defecto	Significado
SYNAP_API_URL	http://synap-cloud:8000	URL base de la API REST subyacente (nombre de host docker interno en prod).
MCP_PORT	8090	Puerto de escucha.
MCP_RECALL_TIMEOUT_S	10	Tiempo de espera de recall (lectura).
MCP_INGEST_TIMEOUT_S	8	Tiempo de espera de log/ingesta (escritura).
MCP_DEFAULT_MAX_RESULTS	10	Número de resultados de recall por defecto.
MCP_STREAM_EVENTS	false	También informar un intercambio registrado como turno de conversación para anticipación. Ver arriba antes de activar.
MCP_EVENTS_TIMEOUT_S	4	Tiempo de espera del informe de turno. Mejor esfuerzo; un fallo nunca cambia la respuesta de una herramienta.
LOG_LEVEL	INFO	Nivel de log.
ENVIRONMENT	production	Informado en /health.

No se configura ninguna clave de API de Synap en el servidor — la clave del usuario final llega por petición como token Bearer.

Consulta la documentación de Synap MCP para guías de configuración de plataformas (Gumloop, n8n) y detalles de despliegue.