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

TL;DR

Sparkient has a full MCP (Model Context Protocol) server that lets you create decision types, trigger training, and make decisions directly from Claude Desktop, Cursor, or VS Code. Cloud MCP connects to mcp.sparkient.ai via Streamable HTTP. Local MCP runs edge bundles via stdio with python -m edge. Setup takes under 5 minutes per IDE.

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) eliminates this by bringing Sparkient directly into your coding environment. Your AI assistant — Claude, Copilot, or Cursor's built-in agent — can interact with Sparkient natively.

What you can do through MCP:

• Create and configure decision types — define options, schemas, and 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 | mcp.sparkient.ai | python -m edge | | Auth | API key | None (local files) | | Capabilities | Full API (CRUD, train, decide) | Edge inference only | | Network required | Yes | No | | Use case | Development, full workflow | Offline, air-gapped, testing |

Cloud MCP gives you full access to the Sparkient API. You can create decision types, train models, and make decisions — everything you can do through the REST API.

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",
      "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

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

{
  "mcpServers": {
    "sparkient-local": {
      "command": "python",
      "args": ["-m", "edge"],
      "env": {
        "BUNDLE_PATH": "C:/path/to/your/moderation.zip"
      }
    }
  }
}

3. Restart Claude Desktop

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",
      "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", "edge"],
      "env": {
        "BUNDLE_PATH": "/path/to/your/bundle.zip"
      }
    }
  }
}

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",
        "headers": {
          "Authorization": "Bearer YOUR_SPARKIENT_API_KEY"
        }
      }
    }
  }
}

3. Reload VS Code

Local MCP (Edge)

{
  "mcp": {
    "servers": {
      "sparkient-local": {
        "command": "python",
        "args": ["-m", "edge"],
        "env": {
          "BUNDLE_PATH": "/path/to/your/bundle.zip"
        }
      }
    }
  }
}

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. The input should include subject, body, customer tier (free/pro/enterprise), and number of open tickets."

Agent: Uses the create_decision_type MCP tool to call the Sparkient API and creates the decision type with the appropriate schema.

Adding Rules

You: "Add a rule that automatically marks enterprise customer tickets as urgent."

Agent: Calls the update_decision_type tool to add the CEL rule ctx.customer_tier == 'enterprise' ? 'urgent' : null.

Training

You: "Train the support triage model."

Agent: Triggers training via the train_model tool. You can ask "What's the training status?" and the agent will check progress.

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:

{
  "decision": "urgent",
  "confidence": 0.94,
  "latency_ms": 36,
  "stage": "classifier"
}

Iterating on the Model

You: "The model is classifying password reset requests as 'normal' but we want those to be 'urgent' for enterprise customers. Can you add a rule for that?"

Agent: Adds the rule ctx.customer_tier == 'enterprise' && ctx.body.contains('password') ? 'urgent' : null and confirms the update.

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 | | update_decision_type | Update options, schema, or rules | | make_decision | Call /decide with input data | | train_model | Trigger model training | | get_training_status | Check training progress | | add_examples | Upload training examples | | get_metrics | Retrieve model performance metrics | | export_bundle | Download an edge bundle |

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. "Add a rule to auto-reject if the user has 5+ previous violations" → Agent adds the CEL rule

3. "Train the model" → Agent triggers training (takes 3-8 minutes)

4. "What's the training status?" → Agent checks and reports: "Training complete. F1: 0.91, Accuracy: 0.93"

5. "Test it with: 'You're terrible at this game, uninstall'" → Agent calls decide: {"decision": "approve", "confidence": 0.78}

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 downloads the bundle to your project directory

The entire workflow happens without leaving your IDE. No dashboard, no curl, no context switching.

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 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'"

• Ensure the BUNDLE_PATH environment variable points to a valid .zip edge bundle
• Use an absolute path, not a relative one

"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 adds network round-trip time to the decision latency — typically under 100ms for the decision plus 50-200ms for the network, depending on your location. Local MCP runs everything in-process at sub-10ms. For development and testing, the difference is negligible. For production edge cases, local MCP is faster.

Does MCP work with other AI assistants? Any AI assistant that supports the MCP protocol can connect to Sparkient's server. The Streamable HTTP transport (cloud) and stdio transport (local) are standard MCP transports. As more tools adopt MCP, Sparkient will work with them automatically.

MCP brings Sparkient into your development flow. Create, train, test, and deploy decision types without leaving your IDE.

Get your API key from the free tier — 5,000 credits, no credit card — and connect in under 5 minutes.