Sparkient MCP Server

API de Inteligência de Decisão abaixo de 100ms. Decisões estruturadas instantâneas para moderação de conteúdo, detecção de fraudes, triagem de tickets e fluxos de aprovação.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Sparkient

Servidor MCP (Model Context Protocol) para a API de inteligência de decisões Sparkient. Conecte agentes de IA a 14 ferramentas para criar, treinar, cancelar, chamar, inspecionar e obter instruções de exportação de borda para modelos de decisão. Decisões compiladas na nuvem visam um caminho de modelo abaixo de 100ms; a latência ponta a ponta do MCP também inclui o cliente e a rede.

Início Rápido

Servidor na Nuvem (Recomendado)

O servidor MCP na nuvem em mcp.sparkient.ai encapsula a API REST do Sparkient como ferramentas MCP. Você precisa de uma chave de API do Sparkient para se conectar.

Claude Desktop

O Claude Desktop não carrega servidores remotos de claude_desktop_config.json. Seus conectores remotos personalizados usam servidores sem autenticação ou baseados em OAuth, enquanto o MCP na nuvem do Sparkient atualmente usa uma chave de API no cabeçalho Authorization. Use Cursor ou VS Code para o servidor na nuvem, ou use o servidor de borda local documentado abaixo. Consulte as orientações de conectores remotos da Anthropic.

Cursor

Nas Configurações do Cursor → MCP, adicione:

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

VS Code

Crie .vscode/mcp.json no seu projeto:

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

Smithery

Instale via Smithery:

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

Desenvolvimento 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

Mantenha a chave de API do Sparkient no cliente MCP, não no processo do servidor. Por exemplo, aponte o Cursor para o proxy local e envie o cabeçalho de portador em cada requisição:

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

Ferramentas Disponíveis

Ferramenta	Descrição
`make_decision`	Faz uma decisão medida e registrada; a API atual define tanto `escalate` quanto `fallback_used` para estágios de escalonamento ou fallback, então inspecione `stage` para distingui-los
`batch_decisions`	Faz até 50 decisões ordenadas; posições com falha são `null` com um erro indexado e não devem ser executadas
`list_decision_types`	Lista tipos de decisão com paginação
`get_decision_type`	Obtém metadados, a versão ativa da configuração e o status de implantação
`create_decision_type`	Cria um tipo somente classificador por padrão, com regras CEL estruturadas, esquema de entrada opcional, limites de confiança e escalonamento explícito para LLM ao vivo
`add_examples`	Adiciona exemplos rotulados e retorna os registros de exemplo criados
`generate_examples`	Gera exemplos sintéticos via Gemini e retorna os registros criados
`train_model`	Dispara treinamento assíncrono após pelo menos 38 exemplos rotulados por opção
`get_training_status`	Consulta o status do treinamento e o progresso das etapas
`cancel_training`	Cancela com segurança a tentativa exata da política ativa
`get_decision_logs`	Consulta registros de decisões passadas
`get_metrics`	Obtém agregados da organização das últimas 24 horas, incluindo taxas de compilação e escalonamento
`get_credits`	Verifica saldo de créditos, informações do plano e o carimbo de redefinição da API
`get_edge_export_instructions`	Obtém a URL REST autenticada e o caminho do painel para baixar um pacote de borda Growth/Scale elegível; não transfere o ZIP pelo MCP

Cada tipo de decisão armazena até 5.000 exemplos, enquanto a cota de treinamento específica do plano pode ser menor. Um lote add_examples que excederia o limite de armazenamento falha sem adicionar parcialmente. Perto do limite, generate_examples pode criar apenas o número restante de exemplos.

Recursos Disponíveis

URI	Descrição
`sparkient://decision-types`	Lista todos os tipos de decisão (para descoberta por agentes)
`sparkient://decision-types/{decision_type_id}`	Esquema completo de um tipo de decisão específico por UUID

Descoberta

O Sparkient anuncia metadados experimentais de descoberta por meio de seu Catálogo de IA e Cartão de Servidor MCP em https://mcp.sparkient.ai/mcp/server-card. O cartão é apenas informativo; a conexão MCP ao vivo autenticada é a autoridade para identidade e capacidades em tempo de execução. As duas rotas /.well-known/mcp... são aliases de compatibilidade, não locais padrão de descoberta de cartão. Páginas de diretórios de terceiros, incluindo Smithery, são espelhos em cache independentes e podem ficar desatualizadas em relação a um lançamento; verifique as ferramentas e afirmações exibidas contra a conexão ao vivo antes de confiar nelas.

Configuração do Smithery

O Smithery descobre ferramentas escaneando o servidor ao vivo. O servidor MCP inclui middleware que fornece metadados de ferramentas para scanners de diretório que não seguem o handshake completo do MCP (enviando tools/list sem initialize).

Detalhes importantes da implementação:

Modo HTTP sem estado (stateless_http=True): Necessário para Cloud Run, onde requisições são roteadas para instâncias diferentes.
Middleware de scanner (UnknownMethodGuard): Intercepta requisições de descoberta sem sessão e fornece metadados de ferramentas diretamente da instância FastMCP. Também retorna -32601 para métodos não padrão como ai.smithery/events/list.
Autenticação: O gateway do Smithery passa a chave de API do usuário pelo cabeçalho Authorization.

Adicionando a um Novo Diretório

A maioria dos diretórios MCP descobre capacidades conectando-se ao servidor e chamando tools/list. O servidor foi projetado para responder corretamente a ambos:

Clientes MCP padrão — initialize → notifications/initialized → tools/list (retorna via SSE)
Scanners de diretório — tools/list diretamente sem initialize (retorna via JSON)

Uso com Frameworks de Agentes de IA

Os exemplos documentados cobrem LangChain/LangGraph e LlamaIndex usando seus adaptadores MCP. Nenhum pacote dedicado do Sparkient é necessário; ambos enviam a chave de API do Sparkient no cabeçalho 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 de Borda Local

Para decisões locais sem dependência de rede após o download do pacote, use o servidor MCP de borda e faça benchmark no hardware de destino:

pip install "sparkient-edge[all]"

Configuração do Claude Desktop:

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

O servidor de borda usa pacotes de borda baixados (regras CEL + modelos ONNX) para inferência local. Abra o tipo de decisão no painel do Sparkient e escolha Exportar, ou chame get_edge_export_instructions para a URL de download REST protegida e os requisitos de autenticação. A ferramenta MCP não transfere o ZIP em si.

Consulte sparkient-edge no PyPI para detalhes.

Variáveis de Ambiente

Variável	Padrão	Descrição
`SPARKIENT_API_URL`	`https://api.sparkient.ai`	URL base da API do Sparkient
`PORT`	`8080`	Porta HTTP para o servidor MCP

Arquitetura

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)

O servidor MCP é um wrapper fino sem estado. Cada requisição é tratada de forma independente — sem rastreamento de sessão. Múltiplas instâncias do Cloud Run atendem requisições concorrentes atrás de uma única URL.