Sparkient MCP Server

MCP (Model Context Protocol) server for the Sparkient decision intelligence API. Connect AI agents to 14 tools for creating, training, cancelling, calling, inspecting, and obtaining edge-export instructions for decision models. Compiled cloud decisions target an under-100ms model path; end-to-end MCP latency also includes the client and network.

Quick Start

Cloud Server (Recommended)

The cloud MCP server at `mcp.sparkient.ai` wraps the Sparkient REST API as MCP tools. You need a Sparkient API key to connect.

Claude Desktop

Claude Desktop does not load remote servers from `claude_desktop_config.json`. Its custom remote connectors use authless or OAuth-based servers, while Sparkient's cloud MCP currently uses an API key in the `Authorization` header. Use Cursor or VS Code for the cloud server, or use the local edge server documented below. See Anthropic's remote connector guidance.

Cursor

In Cursor Settings → MCP, add:

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

VS Code

Create `.vscode/mcp.json` in your project:

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

Smithery

Install via Smithery:

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

Local Development

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

Keep the Sparkient API key in the MCP client, not in the server process. For

example, point Cursor at the local proxy and send the bearer header on every

request:

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

Available Tools

Each decision type stores up to 5,000 examples, while the plan-specific training allowance may be lower. An `add_examples` batch that would exceed the storage limit fails without partially adding it. Near the limit, `generate_examples` may create only the remaining number of examples.

Available Resources

Discovery

Sparkient advertises experimental discovery metadata through its AI Catalog and MCP Server Card at `https://mcp.sparkient.ai/mcp/server-card`. The card is advisory; the authenticated live MCP connection is authoritative for runtime identity and capabilities. The two `/.well-known/mcp...` routes are compatibility aliases, not standard card-discovery locations. Third-party directory pages, including Smithery, are independently cached mirrors and can lag a release; verify their displayed tools and claims against the live connection before relying on them.

Smithery Configuration

Smithery discovers tools by scanning the live server. The MCP server includes middleware that serves tool metadata to directory scanners that don't follow the full MCP handshake (sending `tools/list` without `initialize`).

Key implementation details:

• Stateless HTTP mode (`stateless_http=True`): Required for Cloud Run where requests route to different instances.
• Scanner middleware (`UnknownMethodGuard`): Intercepts discovery requests without a session and serves tool metadata directly from the FastMCP instance. Also returns `-32601` for non-standard methods like `ai.smithery/events/list`.
• Auth: Smithery's gateway passes the user's API key via the `Authorization` header.

Adding to a New Directory

Most MCP directories discover capabilities by connecting to the server and calling `tools/list`. The server is designed to respond correctly to both:

1. Standard MCP clients — `initialize` → `notifications/initialized` → `tools/list` (returns via SSE)

2. Directory scanners — `tools/list` directly without `initialize` (returns via JSON)

Use with AI Agent Frameworks

The documented examples cover LangChain/LangGraph and LlamaIndex using their MCP adapters. No dedicated Sparkient package is needed; both send the Sparkient API key in the `Authorization` header.

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

Local Edge MCP Server

For local decisions with no network dependency after bundle download, use the edge MCP server and benchmark it on the target hardware:

pip install "sparkient-edge[all]"

Claude Desktop config:

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

The edge server uses downloaded edge bundles (CEL rules + ONNX models) for local inference. Open the decision type in the Sparkient dashboard and choose Export, or call `get_edge_export_instructions` for the protected REST download URL and authentication requirements. The MCP tool does not transfer the ZIP itself.

See sparkient-edge on PyPI for details.

Environment Variables

Architecture

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)

The MCP server is a stateless thin wrapper. Each request is handled independently — no session tracking. Multiple Cloud Run instances serve concurrent requests behind a single URL.