How to Connect Sparkient to Claude, Cursor, and VS Code via MCP

TL;DR

Sparkient exposes 14 cloud MCP tools for creating decision types, adding examples, training, deciding, inspecting usage, and getting protected edge-export instructions. Cloud MCP connects to https://mcp.sparkient.ai/mcp via Streamable HTTP. Local MCP runs a separately downloaded edge bundle over stdio with python -m sparkient_edge.

The Problem: Context Switching Kills Flow

Building a decision pipeline typically means bouncing between your IDE, the Sparkient dashboard, API docs, and a terminal running curl commands. You're writing code, switching tabs to check your decision type schema, switching back to write the API call, switching again to check training status.

MCP (Model Context Protocol) can reduce this switching by exposing Sparkient tools inside a compatible coding environment. Your coding agent can call the published workflow through its MCP client.

What you can do through MCP:

• Create decision types — define outcomes and optional rules conversationally
• Upload training examples — paste examples directly into the chat
• Trigger training — start a training run and monitor progress
• Make decisions — call /decide with test inputs and see results inline
• Get edge-export instructions — receive the protected REST endpoint and dashboard route without transferring the ZIP through MCP
• Inspect model performance — check metrics, confidence distributions, and logs

Cloud MCP vs. Local MCP

Sparkient offers two MCP server modes:

| | Cloud MCP | Local MCP | |---|---|---| | Transport | Streamable HTTP | stdio | | Endpoint | https://mcp.sparkient.ai/mcp | python -m sparkient_edge | | Auth | API key | None (local files) | | Capabilities | 15 published tools for creation, examples, training, decisions, inspection, and edge-export guidance | Three tools for loading, inspecting, and running an edge bundle | | Network required | Yes | No | | Use case | Development and cloud management | Offline, air-gapped, testing |

Cloud MCP covers the published agent workflow, but it is not a one-to-one wrapper for every REST endpoint. For example, the current MCP surface creates and reads decision types but does not update an existing definition.

Local MCP runs edge bundles locally. It's for offline inference — making decisions against a pre-trained model without any network access.

Setup: Claude Desktop

Cloud MCP

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 below. Anthropic documents the current constraint in its remote connector guidance.

Local MCP (Edge)

1. Install the edge package:

pip install "sparkient-edge[all]"

2. Add the local server to your Claude Desktop config:

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

3. Restart Claude Desktop, then call load_edge_bundle with the absolute path to the exported ZIP before making a decision.

Setup: Cursor

Cloud MCP

1. Open Cursor Settings → MCP
2. Click "Add MCP Server"
3. Add the configuration:

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

4. The Sparkient tools should appear in Cursor's agent tool list

Local MCP (Edge)

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

Setup: VS Code

Cloud MCP

1. Create .vscode/mcp.json in the workspace (or open your user-profile mcp.json).
2. Add the Sparkient server:

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

3. Start the server from VS Code's MCP view. See the official VS Code MCP configuration reference.

Local MCP (Edge)

{
  "servers": {
    "sparkient-local": {
      "command": "python",
      "args": ["-m", "sparkient_edge"]
    }
  }
}

Example Agent Interactions

Once MCP is connected, you interact with Sparkient through natural language. Here are real workflows:

Creating a Decision Type

You: "Create a new decision type called 'support-triage' that classifies support tickets as urgent, normal, or low priority, with an enterprise-ticket rule included in the initial definition."

Agent: Uses create_decision_type with the outcomes, rule, and optional input schema. The tool creates a new decision type; use the dashboard or REST API to update an existing definition.

Training

You: "Train the support triage model."

Agent: Triggers training via the train_model tool. You can ask "What's the training status?" to inspect its durable attempt and heartbeat, or ask the agent to cancel it safely.

Making Decisions

You: "Test the triage model with this ticket — Subject: 'Payment processing broken', Body: 'None of our customers can complete checkout. We're losing revenue every minute.', Customer tier: pro, Open tickets: 0"

Agent: Calls the make_decision tool and returns:

The agent returns the structured API result, including the decision, confidence, stage, and measured latency for that request.

Iterating on the Model

Use get_decision_logs to inspect outcomes and add_examples to submit reviewed corrections. Retraining is deliberate: add representative corrected examples, trigger train_model, review the new metrics, and deploy according to your policy. Production logs do not label themselves or retrain a model automatically.

Available MCP Tools

Cloud MCP Tools

| Tool | Description | |------|-------------| | create_decision_type | Create a new decision type with options, schema, and rules | | list_decision_types | List all decision types in your organisation | | get_decision_type | Get details of a specific decision type | | make_decision | Call /decide with input data | | batch_decisions | Submit up to 50 decisions in one request | | train_model | Trigger model training | | get_training_status | Check training progress | | cancel_training | Safely cancel the exact active policy attempt | | add_examples | Upload training examples | | generate_examples | Generate synthetic examples with the teacher model | | get_decision_logs | Inspect paginated decision logs | | get_metrics | Retrieve model performance metrics | | get_credits | Inspect the current plan and credit balance | | get_edge_export_instructions | Return the protected REST endpoint and dashboard route; it does not transfer the ZIP |

Local MCP Tools (Edge)

| Tool | Description | |------|-------------| | make_decision | Run a prediction against the local edge bundle | | load_edge_bundle | Load a different edge bundle | | get_bundle_info | Get metadata about the current bundle |

Workflow: What MCP Covers

Most setup and testing can happen through a compatible IDE client. Reviewed deployment, definition edits, and protected edge downloads may still use the REST API or dashboard.

1. "Create a content moderation decision type with approve/review/reject options" → Agent creates the decision type via MCP

2. "Generate a starter set of examples" → Agent calls generate_examples

3. "Once the examples meet the readiness requirements, train the model" → Agent triggers an asynchronous training run

4. "What's the training status?" → Agent reports the actual progress and resulting metrics

5. "Test it with this held-out input" → Agent calls make_decision and returns the measured result

6. "That should be 'review' — it's borderline. Add it as a training example labelled 'review'" → Agent uploads the example

7. "Retrain with the new example" → Agent triggers retraining

8. "Tell me how to export an edge bundle for offline use" → Agent calls get_edge_export_instructions; download the ZIP through the protected REST route or dashboard

The edge ZIP itself never travels through MCP.

Troubleshooting

"MCP server not connecting"

• Check that your API key is valid and has remaining credits
• For cloud MCP, ensure mcp.sparkient.ai is accessible from your network
• For local MCP, verify pip install "sparkient-edge[all]" completed successfully and Python is in your PATH

"Tools not appearing in the tool list"

• Restart your IDE after adding the MCP configuration
• For local MCP in Claude Desktop, check the server status indicator
• In Cursor, verify the server appears in Settings → MCP

"Local MCP: 'Bundle not found'"

• Call load_edge_bundle with the absolute path to a valid exported .zip file

"Decisions returning low confidence"

• This can be expected for edge cases. When live-LLM escalation is enabled, the cloud path can escalate a configured low-confidence decision. Local MCP returns the local result without a live-LLM call.
• Consider retraining with more examples in the problematic area

FAQ

Do I need a Sparkient account for local MCP? Local decisions make no Sparkient API or live-LLM call after the bundle is downloaded. Export requires an eligible plan and an active deployed policy; local package, runtime, and infrastructure requirements still apply.

Can I use both cloud and local MCP simultaneously? Yes. Configure both servers with different names (e.g., sparkient and sparkient-local). Your AI assistant will have access to tools from both. Use cloud MCP for training and management, local MCP for fast offline inference.

What's the latency difference between cloud MCP and local MCP decisions? Cloud MCP includes the Sparkient API and network path; local MCP runs the exported bundle without that network dependency. Benchmark end-to-end latency from the actual client and target hardware before choosing.

Does MCP work with other AI assistants? A compatible AI assistant can connect when it supports the required MCP transport and lets you configure the server. Use Streamable HTTP for the cloud endpoint or stdio for the local package, then verify the tool list in that client.

MCP brings Sparkient into your development flow. Create, train, test, and inspect decision types, then get authenticated edge-export instructions when needed.

Get your API key from the free tier—5,000 one-time credits, no credit card—and connect a compatible client.