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

TL;DR

Sparkient exposes 15 cloud MCP tools for creating decision types, adding examples, training, retrying or safely cancelling training, deciding, inspecting usage, and exporting edge bundles. Cloud MCP connects to https://mcp.sparkient.ai/mcp via Streamable HTTP. Local MCP runs a 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 AI assistant 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
• Export edge bundles — download bundles for offline deployment
• 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, retry and cancellation, decisions, inspection, and export | Three tools for loading, inspecting, and running an edge bundle | | Network required | Yes | No | | Use case | Development, full workflow | 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

1. Open Claude Desktop settings (gear icon → "MCP Servers" or edit claude_desktop_config.json)
2. Add the Sparkient server configuration:

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

3. Restart Claude Desktop
4. You should see Sparkient's tools in the MCP tools list (hammer icon)

Local MCP (Edge)

1. Install the edge package:

pip install "sparkient-edge[mcp]"

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": {
      "type": "streamable-http",
      "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. Install the MCP extension for VS Code (if not already included in your AI assistant extension)
2. Add to your workspace or user settings.json:

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

3. Reload VS Code

Local MCP (Edge)

{
  "mcp": {
    "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 and rule. The current tool does not accept an input schema and does not update an existing decision type; use the dashboard or REST API for those edits.

Training

You: "Train the support triage model."

Agent: Triggers training via the train_model tool after the decision type has at least 38 labelled examples for every option. You can ask "What's the training status?" to inspect its durable attempt and heartbeat, retry a failed or cancelled attempt, or ask the agent to cancel an active attempt 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 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 | | retry_training | Retry the latest failed or cancelled training attempt | | 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 | | export_edge_bundle | Return an exported edge bundle for local use |

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: End-to-End via MCP

Here's a complete workflow, done entirely through your IDE's AI chat:

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. "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. "Export an edge bundle for offline use" → Agent calls export_edge_bundle; the tool returns the filename, size, and base64 bundle content for the client to save

These published steps can run from a compatible IDE client. Definition edits or operations outside the MCP surface still use the dashboard or REST API.

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[mcp]" completed successfully and Python is in your PATH

"Tools not appearing in the tool list"

• Restart your IDE after adding the MCP configuration
• In Claude Desktop, check the MCP server status indicator (should show green)
• 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 is expected for edge cases — the model escalates uncertain decisions to the LLM (cloud MCP) or returns the low-confidence result (local MCP)
• Consider retraining with more examples in the problematic area

FAQ

Do I need a Sparkient account for local MCP? No. Local MCP runs entirely offline using a pre-exported edge bundle. You need an account to train the model and export the bundle initially, but once you have the ZIP file, no account or network connection is required.

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, inspect, and export decision types without leaving your IDE.

Get your API key from the free tier—5,000 credits, no credit card—and connect the client you already use.