> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude & MCP

> Connect AI assistants to the VRP solver through the Model Context Protocol for conversational route optimization

## 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).

<Info>
  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.
</Info>

## 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

<Tabs>
  <Tab title="Claude Code">
    ### Prerequisites

    * [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
    * A Solvice API key ([platform.solvice.io](https://platform.solvice.io) → **Settings** → **API Keys**)

    ### Install the plugin

    <Steps>
      <Step title="Set the environment variable">
        Add your API key to your shell profile so it persists across sessions:

        <Tabs>
          <Tab title="macOS / Linux (zsh)">
            ```bash theme={null}
            echo 'export SOLVICE_API_KEY=your-api-key-here' >> ~/.zshrc
            source ~/.zshrc
            ```
          </Tab>

          <Tab title="macOS / Linux (bash)">
            ```bash theme={null}
            echo 'export SOLVICE_API_KEY=your-api-key-here' >> ~/.bashrc
            source ~/.bashrc
            ```
          </Tab>

          <Tab title="Windows">
            Open **System Properties** → **Advanced** → **Environment Variables** → **New**:

            * Variable name: `SOLVICE_API_KEY`
            * Variable value: `your-api-key-here`
          </Tab>
        </Tabs>

        <Warning>
          Never commit API keys to version control. Use environment variables or a secrets manager.
        </Warning>
      </Step>

      <Step title="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:

        ```bash theme={null}
        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                   |
      </Step>

      <Step title="Restart Claude Code and verify">
        Restart Claude Code so it picks up the plugin and environment variable. Then ask:

        ```
        Solve a demo VRP problem
        ```

        <Check>
          Claude calls the `vrp-demo` tool, solves a sample problem, and renders an interactive route map inline.
        </Check>
      </Step>
    </Steps>

    <Accordion title="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:

      ```json .mcp.json theme={null}
      {
        "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.
    </Accordion>
  </Tab>

  <Tab title="Claude Desktop">
    ### Prerequisites

    * [Claude Desktop](https://claude.ai/download) installed (macOS or Windows)
    * A Solvice API key ([platform.solvice.io](https://platform.solvice.io) → **Settings** → **API Keys**)

    ### Add the Solvice connector

    <Steps>
      <Step title="Open Connector settings">
        In Claude Desktop, click your profile icon → **Settings** → **Connectors**.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Authenticate">
        When prompted, enter your Solvice API key to authorize the connection.
      </Step>

      <Step title="Verify the connection">
        Open a new conversation and ask:

        ```
        Solve a demo VRP problem
        ```

        <Check>
          Claude calls the VRP tools and returns an optimized solution with score and trip details.
        </Check>
      </Step>
    </Steps>

    <Note>
      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".
    </Note>
  </Tab>

  <Tab title="Claude.ai (Projects)">
    ### Prerequisites

    * A [Claude.ai](https://claude.ai) account with Projects access
    * A Solvice API key ([platform.solvice.io](https://platform.solvice.io) → **Settings** → **API Keys**)

    ### Connect the MCP server

    <Steps>
      <Step title="Create a project">
        In Claude.ai, create a new **Project** and open its settings.
      </Step>

      <Step title="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`
      </Step>

      <Step title="Add custom instructions (optional)">
        Under **Custom instructions**, paste the [Solvice system prompt](https://github.com/solvice/claude-plugin/blob/main/project/system-prompt.md). This teaches Claude how to interpret VRP scores, select the right tools, and format responses with exact field paths.
      </Step>

      <Step title="Verify the connection">
        In a new conversation within the project, ask:

        ```
        Generate a demo VRP problem and solve it
        ```

        <Check>
          Claude calls the VRP tools and returns an optimized solution with score and trip details.
        </Check>
      </Step>
    </Steps>

    <Note>
      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".
    </Note>
  </Tab>

  <Tab title="Other MCP clients">
    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.

    <Info>
      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.
    </Info>
  </Tab>
</Tabs>

### Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    The API key is missing or invalid. Verify the environment variable is set:

    ```bash theme={null}
    echo $SOLVICE_API_KEY
    ```

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

  <Accordion title="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}"`
  </Accordion>

  <Accordion title="Skills not showing up">
    Skills require the `.claude/skills/solvice/` directory with `SKILL.md` files inside each skill folder. Verify the structure:

    ```bash theme={null}
    ls .claude/skills/solvice/*/SKILL.md
    ```

    If empty, re-copy from the plugin repository. Skills are optional — tools work without them.
  </Accordion>
</AccordionGroup>

***

## 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                |

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

***

## Interactive Visualizations

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

<CardGroup cols={2}>
  <Card title="Route Map" icon="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`.
  </Card>

  <Card title="Score Dashboard" icon="chart-bar">
    Hard/medium/soft score breakdown, constraint violation table (sortable), and resource utilization bars.

    Triggered by `vrp-get-explanation`.
  </Card>

  <Card title="What-If Builder" icon="arrows-rotate">
    Drag jobs between routes and see instant score re-calculation. Compare original vs. modified scores side-by-side.

    Triggered by `vrp-what-if`.
  </Card>

  <Card title="Gantt Chart" icon="calendar">
    Timeline view for shift scheduling solutions (Fill and Create solvers).

    Triggered by `fill-get-solution` or `create-get-solution`.
  </Card>
</CardGroup>

***

## 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.

<Note>
  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").
</Note>

***

## 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

<CardGroup cols={2}>
  <Card title="VRP Quickstart" icon="rocket" href="/guides/vrp/quickstart">
    Build your first VRP request with the REST API
  </Card>

  <Card title="Scoring & Constraints" icon="scale-balanced" href="/guides/vrp/concepts/scoring-explanation">
    Understand hard, medium, and soft scores
  </Card>

  <Card title="Request Schema" icon="code" href="/guides/vrp/schemas/request">
    Full VRP request schema reference
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/vrp/introduction">
    Complete REST endpoint documentation
  </Card>
</CardGroup>