Zaslat MCP Server

Connect AI assistants to the Zaslat.cz shipping platform via the Model Context Protocol. Create shipments, fetch rates, track parcels, and search pickup points — all through natural language.

<section id="why-mcp">
  <h2>Why MCP — the third interface to logistics</h2>
  <p>Zaslat has long offered two ways to ship: the <strong>web app</strong> for humans and the <strong>REST API</strong> for systems. MCP is the third — built for AI assistants that act on behalf of a real user, with their account, their addresses, and their carrier contracts.</p>
  <p>Where the REST API needs a clean integration and a developer behind it, MCP shines on <strong>the messy stuff in between</strong>:</p>
  <ul>
    <li>An Excel sheet with addresses in three different formats — just upload it and ask the assistant to send them all.</li>
    <li>A customer order that arrived as plain text in an email — paste it, get a shipment.</li>
    <li>Quick questions like <em>“what’s the cheapest way to send 2 kg to Berlin tomorrow?”</em> answered in seconds.</li>
    <li>One-off pickups, bulk cancellations, label reprints — without clicking through the dashboard or writing a script.</li>
  </ul>
  <p>The Zaslat MCP Server connects any MCP-capable assistant — Claude, ChatGPT, n8n, custom agents — to a real Zaslat account. The AI understands context, follows the user’s preferences (default sender, preferred carrier, COD setup), and performs real actions: rate comparisons, shipment creation, tracking, label printing, cancellation.</p>
  <p>It’s a fit for <strong>technically curious users and operations teams</strong> who want to automate shipping without owning an integration project. If you can describe what you need in plain language, the assistant can do it.</p>
</section>

<section id="quick-start">
  <h2>Quick start (Claude.ai / Claude Desktop)</h2>
  <ol>
    <li>Settings → <strong>Connectors</strong> → <strong>Add custom connector</strong></li>
    <li>URL: <code>https://mcp.zaslat.cz/mcp</code></li>
    <li>Choose <strong>OAuth</strong> — you will be redirected to the Zaslat login page</li>
    <li>Approve access — the connector is ready</li>
  </ol>
</section>

<section id="authentication">
  <h2>Authentication</h2>
  <p>The server accepts two credential types. Both are validated against the Zaslat backend on <code>initialize</code> and revalidated every 30 minutes for the lifetime of the MCP session.</p>

  <h3>OAuth 2.1 (recommended)</h3>
  <p>The server advertises its authorization metadata at:</p>
  <pre><code>GET https://mcp.zaslat.cz/.well-known/oauth-protected-resource</code></pre>
  <p>MCP clients that support OAuth (Claude.ai, Claude Desktop) discover the authorization server automatically and run the standard authorization-code flow with PKCE against <code>api.zaslat.cz</code>.</p>
  <p><strong>Scopes:</strong> <code>rates</code>, <code>shipments:read</code>, <code>shipments:write</code></p>
</section>

<section id="api-key">
  <h3>API key</h3>
  <p>For headless clients (n8n, scripts, custom agents) pass a Zaslat API key in the <code>X-ApiKey</code> header:</p>
  <pre><code>POST /mcp HTTP/1.1

Host: mcp.zaslat.cz X-ApiKey: <your-api-key> Content-Type: application/json

You can generate an API key after logging in at app.zaslat.cz under Settings → Integrations → API integration.

<section id="tools">
  <h2>Tools</h2>
  <p>The Zaslat MCP Server exposes 9 tools covering the full shipping workflow — from rate comparison and parcel point search through shipment creation, label printing, tracking, and cancellation.</p>

  <h3>Rates and information</h3>
  <table>
    <thead><tr><th>Tool</th><th>Description</th><th class="center">Modifies data</th></tr></thead>
    <tbody>
      <tr><td><code>get_rates</code></td><td>Compare carrier rates for a given route and package list.</td><td class="center">No</td></tr>
      <tr><td><code>get_profile</code></td><td>Load user profile, default sender address, and account settings.</td><td class="center">No</td></tr>
      <tr><td><code>search_parcel_points</code></td><td>Find nearest pickup / drop-off points by address, ZIP, or carrier.</td><td class="center">No</td></tr>
    </tbody>
  </table>

  <h3>Shipment management</h3>
  <table>
    <thead><tr><th>Tool</th><th>Description</th><th class="center">Modifies data</th></tr></thead>
    <tbody>
      <tr><td><code>create_shipment</code></td><td>Create a new shipment (Home2Home, Shop2Home, Home2Shop, Shop2Shop).</td><td class="center"><strong>Yes</strong></td></tr>
      <tr><td><code>cancel_shipment</code></td><td>Cancel a shipment that has not yet been picked up by the carrier.</td><td class="center"><strong>Yes</strong></td></tr>
    </tbody>
  </table>

  <h3>Listing and tracking</h3>
  <table>
    <thead><tr><th>Tool</th><th>Description</th><th class="center">Modifies data</th></tr></thead>
    <tbody>
      <tr><td><code>list_shipments</code></td><td>List shipments with filters and pagination.</td><td class="center">No</td></tr>
      <tr><td><code>get_shipment_detail</code></td><td>Full shipment details including the carrier tracking number.</td><td class="center">No</td></tr>
      <tr><td><code>track_shipment</code></td><td>Tracking status with event history.</td><td class="center">No</td></tr>
    </tbody>
  </table>

  <h3>Labels</h3>
  <table>
    <thead><tr><th>Tool</th><th>Description</th><th class="center">Modifies data</th></tr></thead>
    <tbody>
      <tr><td><code>print_label</code></td><td>Generate a shipping label (PDF link or base64).</td><td class="center">No</td></tr>
    </tbody>
  </table>
</section>

<section id="workflow">
  <h2>Typical workflow</h2>
  <pre><code>1. get_profile           → Load default sender address

2. get_rates → Compare carrier rates 3. search_parcel_points → Find pickup point (Home2Shop / Shop2Shop) 4. create_shipment → Create shipment with the selected carrier 5. print_label → Download label for printing 6. track_shipment → Track shipment status

<section id="examples">
  <h2>Example prompts</h2>

  <h3>Comparing rates</h3>
  <blockquote><p>What are the shipping rates for a 30×20×15 cm, 3 kg package from Prague to Brno?</p></blockquote>
  <blockquote><p>Compare carrier prices for a 5 kg shipment to Bratislava.</p></blockquote>
  <blockquote><p>How much does it cost to ship 2 packages from Ostrava to Berlin?</p></blockquote>

  <h3>Creating a shipment</h3>
  <blockquote><p>Send a package via DPD to Jan Novák, Příčná 5, Brno 602 00, 2 kg.</p></blockquote>
  <blockquote><p>Create a Zásilkovna shipment to pickup point 12345, recipient Eva Malá, phone 777123456.</p></blockquote>
  <blockquote><p>Order PPL with cash on delivery 500 CZK to account 1234567890/0100.</p></blockquote>

  <h3>Tracking and listing</h3>
  <blockquote><p>Where is my shipment IZ123456?</p></blockquote>
  <blockquote><p>Show me my last 10 shipments.</p></blockquote>
  <blockquote><p>Find all undelivered DPD shipments from last week.</p></blockquote>
  <blockquote><p>Show me shipments with unpaid COD from the last month.</p></blockquote>

  <h3>Labels</h3>
  <blockquote><p>Print the label for shipment IZ123456.</p></blockquote>
  <blockquote><p>I need an A6 label for a thermal printer.</p></blockquote>

  <h3>Bulk shipping</h3>
  <blockquote><p>(upload Excel file) Send all shipments from this file via DPD.</p></blockquote>

  <h3>Cancelling</h3>
  <blockquote><p>Cancel shipment IZ123456.</p></blockquote>
</section>

<section id="conventions">
  <h2>Defaults &amp; conventions</h2>
  <ul>
    <li><strong>Default package size:</strong> 20 × 20 × 20 cm, 1 kg when dimensions are omitted. For FedEx and UPS always provide exact dimensions — every centimeter affects pricing.</li>
    <li><strong>Shipment IDs:</strong> Zaslat shipments use the format <code>IZxxxxx</code> (e.g. <code>IZ123456</code>). This differs from the carrier tracking number — retrieve it via <code>get_shipment_detail</code>.</li>
    <li><strong>Country codes:</strong> Use ISO 3166-1 alpha-2 (<code>CZ</code>, <code>SK</code>, <code>DE</code>).</li>
    <li><strong>Postal codes:</strong> No spaces (<code>60200</code>, not <code>602 00</code>).</li>
  </ul>
</section>

<section id="support">
  <h2>Support</h2>
  <ul>
    <li>Email: <a href="mailto:admin@zaslat.cz">admin@zaslat.cz</a></li>
  </ul>
</section>