import { Button } from "zudoku/ui/Button";
import { ExternalLink } from "zudoku/icons";
import { Secret } from "zudoku/ui/Secret";
import { Value } from "zudoku/ui/Value";

# MCP Server

The MCP (Model Context Protocol) Server is a smart way to connect your Large Language Models (LLMs) with our e-vignette API. This allows you to automate the process of purchasing vignettes based on user requests.


<Stepper>
1. **Add MCP Server**


    You can use OpenAI playground or another tool –{" "} <a href="https://platform.openai.com/chat/edit?models=gpt-5" target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1 text-primary underline"> Add MCP Server <ExternalLink size={16} className="text-primary" /></a>
    <div className="flex flex-col gap-0 max-w-fit not-prose">
        <span className="text-sm font-medium">MCP Server URL</span>
        <Value
            value="https://sandbox-api.vignette.id/mcp"
            className="w-full"
        />
    </div>

    <Callout type="tip" title="API Key">
        You can find your API key in the [Partner Panel](/wiki/partner-panel) -> For Developers section. Make sure to use the `SANDBOX` key for testing purposes.
    </Callout>
    ![Add MCP Server](/mcp-1.png)
    ![Add MCP Server](/mcp-2.png)


1. **Define Instructions for your Agent**

    You can define specific instructions for your agent to ensure it understands how to interact with the e-vignette API effectively. Here are some example instructions you can use:

    ```
    You are an expert in purchasing vignettes for various countries. Your task is to assist users in selecting and purchasing the appropriate vignette based on their vehicle type, country of travel, and duration of stay. 

    When a user requests a vignette, follow these steps:

    1. Ask for the user's vehicle type (e.g., car, van, moto).
    2. Ask for the country where the vignette is needed.
    3. Ask for the duration of stay (e.g., 10 days, 1 month).
    4. Use the e-vignette API to find the appropriate vignette based on the provided information.
    5. Validate the vehicle plate using the validate_vehicle tool.
    6. Create the order using the create_order tool.
    7. Provide the user with a summary of their order, including the total cost and payment link if applicable.

    Ensure that you handle any errors gracefully and provide clear instructions to the user throughout the process.
    ```

1. **Available MCP Tools**

    The following tools are available through the MCP Server:

    | Tool | Description | Use case |
    |------|-------------|----------|
    | `get_products` | Get available vignettes, tunnels, and bridges | Browse catalog by country, type, vehicle |
    | `get_products_status` | Check provider status | Verify if a country provider is online |
    | `get_users` | List partner users | View all users created through your integration |
    | `get_user_orders` | Get orders for a specific user | View order history for a user by ID |
    | `validate_vehicle` | Validate vehicle plate number | Check plate format before creating order |
    | `create_order` | Create a new vignette order | Purchase a vignette for a vehicle |
    | `get_orders` | List all orders | View order history |
    | `get_order` | Get a specific order by ID | Check order details |
    | `get_order_status` | Check order status | Track order progress (PENDING → ACTIVE) |
    | `cancel_pending_order` | Cancel a pending order | Cancel before activation |
    | `cancel_deferred_order` | Cancel a deferred order | Cancel a future-dated order |

1. **Example Agent Flow**

    A typical vignette purchase flow through the MCP Server:

    ```
    User: "I need a 10-day vignette for Hungary for my car with plate W-12345X"

    Agent flow:
    1. get_products(country=hu, type=vignette)     → find matching product
    2. validate_vehicle(plate=W-12345X, country=at) → validate plate format  
    3. create_order(product, vehicle, user data)     → create the order
    4. get_order_status(order_id)                    → confirm order status
    ```

    <Callout type="caution" title="Sandbox vs Production">
        Use `https://sandbox-api.vignette.id/mcp` for testing. Switch to `https://api.vignette.id/mcp` for production orders.
    </Callout>

</Stepper>