Claude & MCP

Overview

The Solvice MCP server exposes the VRP API as tools that AI assistants can call directly. You describe a routing problem in natural language, and the assistant builds the request, solves it, and renders interactive visualizations — all within the conversation. This works with any MCP-compatible client. The guide below covers Claude Code (CLI) and Claude.ai (web).

The MCP server uses the same API key as the REST API. All VRP endpoints are available as tools with the same request/response schemas.

What You Get

Capability	Description
15 VRP tools	Solve, evaluate, suggest, change, and inspect routing solutions
Interactive apps	Route map, score dashboard, what-if builder — rendered inline
Guided skills	`/solvice:scaffold` to build requests, `/solvice:debug` to diagnose failures
Documentation resources	Constraint reference, integration patterns, and request schemas available in-context

Setup

Claude Code
Claude Desktop
Claude.ai (Projects)
Other MCP clients

Prerequisites

Claude Code installed
A Solvice API key (platform.solvice.io → Settings → API Keys)

Install the plugin

Set the environment variable

Add your API key to your shell profile so it persists across sessions:

macOS / Linux (zsh)
macOS / Linux (bash)
Windows

echo 'export SOLVICE_API_KEY=your-api-key-here' >> ~/.zshrc
source ~/.zshrc

echo 'export SOLVICE_API_KEY=your-api-key-here' >> ~/.bashrc
source ~/.bashrc

Open System Properties → Advanced → Environment Variables → New:

Variable name: SOLVICE_API_KEY
Variable value: your-api-key-here

Never commit API keys to version control. Use environment variables or a secrets manager.

Install the Solvice plugin

The Solvice plugin bundles the MCP server configuration, guided skills, and slash commands. Installing it wires up the MCP connection automatically — no manual .mcp.json required.In Claude Code, run:

claude plugin install solvice

This registers the MCP server and adds these slash commands:

Command	What it does
`/solvice:quickstart`	Hands-on tour — solve, score, modify, debug
`/solvice:scaffold`	Build a working request through a 5-question interview
`/solvice:debug <id>`	Diagnose constraint violations with field-level fixes
`/solvice:setup`	Verify the MCP connection is working

Restart Claude Code and verify

Restart Claude Code so it picks up the plugin and environment variable. Then ask:

Solve a demo VRP problem

Claude calls the vrp-demo tool, solves a sample problem, and renders an interactive route map inline.

Manual setup (without the plugin)

If you prefer to add the MCP server directly to a project without installing the plugin, create a .mcp.json file in your project root:

.mcp.json

{
  "mcpServers": {
    "solvice": {
      "type": "http",
      "url": "https://api.solvice.io/mcp",
      "headers": {
        "Authorization": "${SOLVICE_API_KEY}"
      }
    }
  }
}

${SOLVICE_API_KEY} is resolved from your environment automatically. You don’t paste the key into this file.

Prerequisites

Claude Desktop installed (macOS or Windows)
A Solvice API key (platform.solvice.io → Settings → API Keys)

Add the Solvice connector

Open Connector settings

In Claude Desktop, click your profile icon → Settings → Connectors.

Add a custom connector

Scroll to the bottom and click Add custom connector. Enter the Solvice MCP server URL:

https://api.solvice.io/mcp

Click Add to proceed.

Authenticate

When prompted, enter your Solvice API key to authorize the connection.

Verify the connection

Open a new conversation and ask:

Solve a demo VRP problem

Claude calls the VRP tools and returns an optimized solution with score and trip details.

Claude Desktop connects to the Solvice MCP server as a remote connector. All VRP tools are available, but skills (slash commands) are specific to Claude Code. You can achieve the same workflows by asking Claude directly — e.g., “Build me a VRP request for field service appointments” or “Debug solve run abc-123”.

Prerequisites

A Claude.ai account with Projects access
A Solvice API key (platform.solvice.io → Settings → API Keys)

Connect the MCP server

Create a project

In Claude.ai, create a new Project and open its settings.

Add the MCP server

Under Integrations, add a new MCP server:

URL: https://api.solvice.io/mcp
Authentication: API key
Header: Authorization: YOUR_API_KEY

Add custom instructions (optional)

Under Custom instructions, paste the Solvice system prompt. This teaches Claude how to interpret VRP scores, select the right tools, and format responses with exact field paths.

Verify the connection

In a new conversation within the project, ask:

Generate a demo VRP problem and solve it

Claude calls the VRP tools and returns an optimized solution with score and trip details.

Claude.ai Projects don’t support skills (slash commands). The same workflows are available by asking Claude directly — e.g., “Build me a VRP request for field service appointments” or “Debug solve run abc-123”.

Any MCP-compatible client can connect to the Solvice server. The connection requires:

Parameter	Value
Server URL	`https://api.solvice.io/mcp`
Transport	HTTP (Streamable HTTP)
Authentication	`Authorization: YOUR_API_KEY` header

Once connected, the client discovers all available tools, resources, and prompts automatically through the MCP protocol.

Interactive visualizations (route map, score dashboard, what-if builder) require the client to support the ext-apps MCP extension. Text-based tool results work with any MCP client.

Troubleshooting

401 Unauthorized

The API key is missing or invalid. Verify the environment variable is set:

echo $SOLVICE_API_KEY

If empty, re-add it to your shell profile and restart your terminal. Then restart Claude Code.

Tool not found / MCP server not connected

If you installed the plugin, restart Claude Code — the MCP server connects at startup. Run /solvice:setup to confirm the connection.If you’re using manual .mcp.json setup, make sure:

The file is in your project root (not a subdirectory)
You restarted Claude Code after creating the file
The JSON is valid (no trailing commas, correct quotes)
The Authorization header is the raw key with no prefix: "${SOLVICE_API_KEY}"

Skills not showing up

Skills require the .claude/skills/solvice/ directory with SKILL.md files inside each skill folder. Verify the structure:

ls .claude/skills/solvice/*/SKILL.md

If empty, re-copy from the plugin repository. Skills are optional — tools work without them.

VRP Tools

The MCP server exposes VRP endpoints as callable tools. Each tool maps to a REST API endpoint with the same request/response format.

Solve & Optimize

Tool	Description	REST equivalent
`vrp-solve-sync`	Solve a routing problem and wait for results	`POST /v2/vrp/solve/sync`
`vrp-solve`	Submit a solve job (async, returns job ID)	`POST /v2/vrp/solve`
`vrp-evaluate-sync`	Score an existing solution synchronously	`POST /v2/vrp/evaluate/sync`
`vrp-evaluate`	Score an existing solution (async)	`POST /v2/vrp/evaluate`
`vrp-suggest-sync`	Get schedule suggestions for unassigned jobs	`POST /v2/vrp/suggest/sync`
`vrp-suggest`	Get suggestions (async)	`POST /v2/vrp/suggest`
`vrp-demo`	Generate and solve a sample problem	`GET /v2/vrp/demo`

Inspect & Modify

Tool	Description	REST equivalent
`vrp-get-solution`	Retrieve optimized routes (renders route map)	`GET /v2/vrp/job/{id}`
`vrp-get-explanation`	Score breakdown and constraint violations (renders dashboard)	`GET /v2/vrp/job/{id}/explanation`
`vrp-get-request`	Original request summary	`GET /v2/vrp/job/{id}/request`
`vrp-get-status`	Job status (queued, solving, solved, failed)	`GET /v2/vrp/job/{id}/status`
`vrp-get-all`	Combined request, solution, and explanation	—
`vrp-get-debug`	Solver internals for constraint tracing	`GET /v2/vrp/job/{id}/debug`

What-If Analysis

Tool	Description
`vrp-change`	Move jobs between routes, reorder stops, then evaluate or re-solve
`vrp-what-if`	Open the interactive drag-and-drop scenario builder

Use vrp-change with operation: "evaluate" to test a change without committing it. Switch to operation: "solve" to apply changes and re-optimize.

Interactive Visualizations

Tools that return solutions or explanations render interactive apps directly in the conversation.

Route Map

Color-coded routes on a live map with numbered stops, click-for-details markers, and a floating KPI bar showing score, distance, and travel time.Triggered by vrp-get-solution.

Score Dashboard

Hard/medium/soft score breakdown, constraint violation table (sortable), and resource utilization bars.Triggered by vrp-get-explanation.

What-If Builder

Drag jobs between routes and see instant score re-calculation. Compare original vs. modified scores side-by-side.Triggered by vrp-what-if.

Gantt Chart

Timeline view for shift scheduling solutions (Fill and Create solvers).Triggered by fill-get-solution or create-get-solution.

Skills (Claude Code)

The Solvice plugin includes skills — guided workflows you invoke with slash commands.

`/solvice:quickstart`

Hands-on tour of the VRP platform. Solves a demo problem, then lets you explore scoring, what-if analysis, debugging, and integration patterns through a menu.

`/solvice:scaffold`

Builds a working VRP request through a five-question interview: job type, scale, time windows, skills, capacity. Solves the request to verify feasibility and auto-fixes up to 3 times if needed. Returns verified JSON you can paste into your integration.

`/solvice:debug <solve-id>`

Diagnoses infeasible solutions and unassigned jobs. Fetches the explanation, maps each violated constraint to a root cause, and returns exact field paths with before/after fix values.

Skills are specific to Claude Code. In Claude.ai Projects, the same workflows are available by asking the assistant directly (e.g., “Build me a VRP request for field service appointments”).

Example Workflows

Build and solve a routing problem

Build a VRP request for 20 delivery jobs across Brussels with 3 vans,
each with 100kg capacity. Jobs have 2-hour time windows. Solve it.

The assistant builds an OnRouteRequest, calls vrp-solve-sync, and renders the route map.

Diagnose a failed solve

Debug solve run abc-123 — why are 5 jobs unassigned?

The assistant calls vrp-get-all, identifies constraint violations, and suggests fixes with exact field paths.

Test a schedule change

What happens if I move job delivery-15 from vehicle-1 to vehicle-2?

The assistant calls vrp-change with operation: "evaluate" and compares the scores.

Next Steps

VRP Quickstart

Build your first VRP request with the REST API

Scoring & Constraints

Understand hard, medium, and soft scores

Request Schema

Full VRP request schema reference

API Reference

Complete REST endpoint documentation

Platform

VRP API

Fill API

Overview

What You Get

Setup

Prerequisites

Install the plugin

Prerequisites

Add the Solvice connector

Prerequisites

Connect the MCP server

Troubleshooting

VRP Tools

Solve & Optimize

Inspect & Modify

What-If Analysis

Interactive Visualizations

Route Map

Score Dashboard

What-If Builder

Gantt Chart

Skills (Claude Code)

`/solvice:quickstart`

`/solvice:scaffold`

`/solvice:debug <solve-id>`

Example Workflows

Build and solve a routing problem

Diagnose a failed solve

Test a schedule change

Next Steps

VRP Quickstart

Scoring & Constraints

Request Schema

API Reference

Platform

VRP API

Fill API

​Overview

​What You Get

​Setup

​Prerequisites

​Install the plugin

​Prerequisites

​Add the Solvice connector

​Prerequisites

​Connect the MCP server

​Troubleshooting

​VRP Tools

​Solve & Optimize

​Inspect & Modify

​What-If Analysis

​Interactive Visualizations

Route Map

Score Dashboard

What-If Builder

Gantt Chart

​Skills (Claude Code)

​/solvice:quickstart

​/solvice:scaffold

​/solvice:debug <solve-id>

​Example Workflows

​Build and solve a routing problem

​Diagnose a failed solve

​Test a schedule change

​Next Steps

VRP Quickstart

Scoring & Constraints

Request Schema

API Reference

Overview

What You Get

Setup

Prerequisites

Install the plugin

Prerequisites

Add the Solvice connector

Prerequisites

Connect the MCP server

Troubleshooting

VRP Tools

Solve & Optimize

Inspect & Modify

What-If Analysis

Interactive Visualizations

Skills (Claude Code)

`/solvice:quickstart`

`/solvice:scaffold`

`/solvice:debug <solve-id>`

Example Workflows

Build and solve a routing problem

Diagnose a failed solve

Test a schedule change

Next Steps