Synap MCP Server

synap-mcp-server

Servidor MCP remoto hospedado (HTTP Streamable) que reexpõe as operações REST públicas existentes do Synap como ferramentas MCP, permitindo que plataformas no-code (Gumloop, n8n) ofereçam memória persistente aos seus agentes apenas com uma URL MCP colada e um token Bearer.

É um adaptador sem estado — sem novo backend, armazenamento ou pipeline. Cada chamada de ferramenta mapeia para uma operação REST existente, e o token Bearer synap_<key> recebido é encaminhado literalmente para synap-cloud, que é o dono da autenticação.

• Endpoint público (produção): https://synap-mcp.maximem.ai/mcp
• Health: https://synap-mcp.maximem.ai/health

Ferramentas

Ferramenta	Operação REST	Observações
log_exchange	POST /api/v1/memories/create (mode=long-range)	Encaminha a cada turno; a extração decide o que persiste. Escopo opcional user_id/customer_id por usuário final; conversation_id opcional.
recall_context	POST /v1/context/{client|user|customer}/fetch (mode=fast)	Caminho crítico; sem IDs ⇒ escopo do cliente. user_id/customer_id opcionais.
list_recent_memories	/v1/context/.../fetch amplo (sem consulta)	Depuração / "teste minha memória". user_id/customer_id opcionais.

Escopo. Não passe IDs ⇒ escopo do cliente (compartilhado por credencial). Passe user_id (e/ou customer_id) em ambos log_exchange e recall_context para manter a memória de cada usuário final separada — preencha com uma expressão do n8n / entrada do Gumloop. Observação: gravações no escopo do cliente não aparecem na página de Memórias do painel (relacional), então o escopo por usuário é recomendado quando a visibilidade no painel for importante.

Cabeçalho Host. O servidor desativa a verificação de rebinding de DNS do transporte MCP (ele fica atrás de um proxy + autenticação Bearer), então qualquer proxy reverso pode encaminhar o Host real — sem necessidade de hack de reescrita de Host.

Executar 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",...}

Testar

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

Configuração (env)

Variável	Padrão	Significado
SYNAP_API_URL	http://synap-cloud:8000	URL base da API REST de apoio (nome de host docker interno em produção).
MCP_PORT	8090	Porta de escuta.
MCP_RECALL_TIMEOUT_S	10	Tempo limite de recall (leitura).
MCP_INGEST_TIMEOUT_S	8	Tempo limite de log/ingestão (gravação).
MCP_DEFAULT_MAX_RESULTS	10	Contagem padrão de resultados de recall.
LOG_LEVEL	INFO	Nível de log.
ENVIRONMENT	production	Informado em /health.

Nenhuma chave de API do Synap é configurada no servidor — a chave do usuário final chega por requisição como um token Bearer.

Consulte a documentação do Synap para guias de configuração de plataforma (Gumloop, n8n) e detalhes de implantação.