Sparkient MCP Server

API de Inteligencia de Decisiones en menos de 100ms. Decisiones estructuradas instantáneas para moderación de contenido, detección de fraude, clasificación de tickets y flujos de aprobación.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Sparkient

Servidor MCP (Protocolo de Contexto de Modelo) para la API de inteligencia de decisiones Sparkient. Conecta agentes de IA a 14 herramientas para crear, entrenar, cancelar, llamar, inspeccionar y obtener instrucciones de exportación perimetral para modelos de decisión. Las decisiones compiladas en la nube apuntan a una ruta de modelo de menos de 100 ms; la latencia total de MCP de extremo a extremo también incluye el cliente y la red.

Inicio Rápido

Servidor en la Nube (Recomendado)

El servidor MCP en la nube en mcp.sparkient.ai envuelve la API REST de Sparkient como herramientas MCP. Necesitas una clave de API de Sparkient para conectarte.

Claude Desktop

Claude Desktop no carga servidores remotos desde claude_desktop_config.json. Sus conectores remotos personalizados utilizan servidores sin autenticación o basados en OAuth, mientras que el MCP en la nube de Sparkient actualmente usa una clave de API en el encabezado Authorization. Usa Cursor o VS Code para el servidor en la nube, o usa el servidor perimetral local documentado a continuación. Consulta la guía de conectores remotos de Anthropic.

Cursor

En Configuración de Cursor → MCP, agrega:

{
  "mcpServers": {
    "sparkient": {
      "url": "https://mcp.sparkient.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code

Crea .vscode/mcp.json en tu proyecto:

{
  "servers": {
    "sparkient": {
      "type": "http",
      "url": "https://mcp.sparkient.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Smithery

Instala a través de Smithery:

npx -y @smithery/cli install sparkient --client claude

Desarrollo Local

cd mcp-server
pip install -e ".[dev]"

# Set the upstream API URL and start the local MCP proxy
export SPARKIENT_API_URL=https://api.sparkient.ai
python -m sparkient_mcp

Mantén la clave de API de Sparkient en el cliente MCP, no en el proceso del servidor. Por ejemplo, apunta Cursor al proxy local y envía el encabezado de portador en cada solicitud:

{
  "mcpServers": {
    "sparkient-local-dev": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Herramientas Disponibles

Herramienta	Descripción
`make_decision`	Realiza una decisión medida y registrada; la API actual establece tanto `escalate` como `fallback_used` para etapas de escalamiento o respaldo, así que inspecciona `stage` para distinguirlas
`batch_decisions`	Realiza hasta 50 decisiones ordenadas; las posiciones fallidas son `null` con un error indexado y no deben ejecutarse
`list_decision_types`	Lista tipos de decisión con paginación
`get_decision_type`	Obtiene metadatos, la versión de configuración activa y el estado de implementación
`create_decision_type`	Crea un tipo solo de clasificador por defecto, con reglas CEL estructuradas, esquema de entrada opcional, umbrales de confianza y escalamiento explícito a LLM en vivo
`add_examples`	Agrega ejemplos etiquetados y devuelve los registros de ejemplo creados
`generate_examples`	Genera ejemplos sintéticos a través de Gemini y devuelve los registros creados
`train_model`	Activa el entrenamiento asíncrono después de al menos 38 ejemplos etiquetados por opción
`get_training_status`	Consulta el estado del entrenamiento y el progreso de las etapas
`cancel_training`	Cancela de forma segura el intento de política activa exacto
`get_decision_logs`	Consulta registros de decisiones pasadas
`get_metrics`	Obtiene agregados de la organización para las últimas 24 horas, incluidas las tasas de compilación y escalamiento
`get_credits`	Verifica el saldo de créditos, la información del plan y la marca de tiempo de reinicio de la API
`get_edge_export_instructions`	Obtiene la URL REST autenticada y la ruta del panel para descargar un paquete perimetral Growth/Scale elegible; no transfiere el ZIP a través de MCP

Cada tipo de decisión almacena hasta 5,000 ejemplos, mientras que la asignación de entrenamiento específica del plan puede ser menor. Un lote add_examples que excedería el límite de almacenamiento falla sin agregarlo parcialmente. Cerca del límite, generate_examples puede crear solo el número restante de ejemplos.

Recursos Disponibles

URI	Descripción
`sparkient://decision-types`	Lista todos los tipos de decisión (para descubrimiento de agentes)
`sparkient://decision-types/{decision_type_id}`	Esquema completo de un tipo de decisión específico por UUID

Descubrimiento

Sparkient anuncia metadatos de descubrimiento experimentales a través de su Catálogo de IA y Tarjeta de Servidor MCP en https://mcp.sparkient.ai/mcp/server-card. La tarjeta es informativa; la conexión MCP en vivo autenticada es la autoridad para la identidad y las capacidades en tiempo de ejecución. Las dos rutas /.well-known/mcp... son alias de compatibilidad, no ubicaciones estándar de descubrimiento de tarjetas. Las páginas de directorios de terceros, incluido Smithery, son espejos almacenados en caché de forma independiente y pueden retrasarse respecto a un lanzamiento; verifica sus herramientas y afirmaciones mostradas contra la conexión en vivo antes de confiar en ellas.

Configuración de Smithery

Smithery descubre herramientas escaneando el servidor en vivo. El servidor MCP incluye middleware que sirve metadatos de herramientas a escáneres de directorios que no siguen el protocolo de enlace MCP completo (enviando tools/list sin initialize).

Detalles clave de implementación:

Modo HTTP sin estado (stateless_http=True): Requerido para Cloud Run donde las solicitudes se enrutan a diferentes instancias.
Middleware de escáner (UnknownMethodGuard): Intercepta solicitudes de descubrimiento sin sesión y sirve metadatos de herramientas directamente desde la instancia de FastMCP. También devuelve -32601 para métodos no estándar como ai.smithery/events/list.
Autenticación: La puerta de enlace de Smithery pasa la clave de API del usuario a través del encabezado Authorization.

Agregar a un Nuevo Directorio

La mayoría de los directorios MCP descubren capacidades conectándose al servidor y llamando a tools/list. El servidor está diseñado para responder correctamente a ambos:

Clientes MCP estándar — initialize → notifications/initialized → tools/list (responde a través de SSE)
Escáneres de directorios — tools/list directamente sin initialize (responde a través de JSON)

Uso con Marcos de Trabajo de Agentes de IA

Los ejemplos documentados cubren LangChain/LangGraph y LlamaIndex usando sus adaptadores MCP. No se necesita un paquete dedicado de Sparkient; ambos envían la clave de API de Sparkient en el encabezado Authorization.

LangChain

pip install langchain langchain-mcp-adapters langchain-openai

import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

async def main():
    client = MultiServerMCPClient({
        "sparkient": {
            "transport": "streamable_http",
            "url": "https://mcp.sparkient.ai/mcp",
            "headers": {"Authorization": "Bearer YOUR_API_KEY"},
        }
    })
    tools = await client.get_tools()
    agent = create_agent(model=ChatOpenAI(model="gpt-4o"), tools=tools)
    result = await agent.ainvoke({
        "messages": [{"role": "user", "content": "Is this spam? 'BUY CHEAP WATCHES NOW!!!'"}]
    })
    print(result)

asyncio.run(main())

LlamaIndex

pip install llama-index-tools-mcp

from llama_index.tools.mcp import BasicMCPClient, McpToolSpec

mcp_client = BasicMCPClient(
    "https://mcp.sparkient.ai/mcp",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
tool_spec = McpToolSpec(client=mcp_client)
tools = tool_spec.to_tool_list()  # All 14 Sparkient tools ready to use

Servidor MCP Perimetral Local

Para decisiones locales sin dependencia de red después de la descarga del paquete, usa el servidor MCP perimetral y evalúalo en el hardware objetivo:

pip install "sparkient-edge[all]"

Configuración de Claude Desktop:

{
  "mcpServers": {
    "sparkient-edge": {
      "command": "python",
      "args": ["-m", "sparkient_edge"]
    }
  }
}

El servidor perimetral usa paquetes perimetrales descargados (reglas CEL + modelos ONNX) para inferencia local. Abre el tipo de decisión en el panel de Sparkient y elige Exportar, o llama a get_edge_export_instructions para la URL de descarga REST protegida y los requisitos de autenticación. La herramienta MCP no transfiere el ZIP en sí.

Consulta sparkient-edge en PyPI para más detalles.

Variables de Entorno

Variable	Predeterminado	Descripción
`SPARKIENT_API_URL`	`https://api.sparkient.ai`	URL base de la API de Sparkient
`PORT`	`8080`	Puerto HTTP para el servidor MCP

Arquitectura

AI Agent (Claude/Cursor/VS Code/LangChain)
    ↓ Streamable HTTP + API Key
Sparkient MCP Server (this package)
    ↓ httpx (async HTTP)
Sparkient REST API (api.sparkient.ai)
    ↓
Decision Pipeline: CEL Rules → ONNX Classifier → Optional Gemini escalation (when enabled)

El servidor MCP es un envoltorio delgado sin estado. Cada solicitud se maneja de forma independiente, sin seguimiento de sesión. Múltiples instancias de Cloud Run atienden solicitudes concurrentes detrás de una sola URL.