Kolumna MCP

Przegląd kolumny MCP

Ten przewodnik to kolumna MCP Superroute w Developer Center: oba serwery, bezpieczeństwo agentów i żywy katalog narzędzi.

• User MCP — zamówienia, trasy, etykiety, podsumowania dla agentów ops/wsparcia — https://api.miliexpress.com/mcp
• Developer MCP — przewodniki, webhooki i przykładowe API dla integratorów — https://api.miliexpress.com/mcp/developer
• Bezpieczeństwo: Bearer połączenia, profile/scope, confirm dla narzędzi wysokiego ryzyka
• Kolejka zatwierdzeń (propose_write + /mcp-approvals)

Czym jest MCP?

Model Context Protocol (MCP) to otwarty standard, który umożliwia asystentom AI, takim jak Claude, Cursor i ChatGPT, interakcję z zewnętrznymi narzędziami i usługami. Pozwala Twojemu AI wykonywać rzeczywiste akcje — takie jak śledzenie przesyłki — bezpośrednio w rozmowie.

Konfigurując serwer MCP Superroute, Twój asystent AI zyskuje dostęp do narzędzi logistycznych bez opuszczania przepływu pracy.

Dwa serwery MCP

Wybierz właściwy serwer. Nie dawaj nienadzorowanym agentom serwera Developer z pełnym dostępem.

Szybki start

Publiczne narzędzia, takie jak śledzenie przesyłek, działają bez uwierzytelniania. Dodaj tę konfigurację do swojego klienta MCP:

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

Uwierzytelniony dostęp

Aby korzystać z narzędzi wymagających uprawnień użytkownika, dodaj token Bearer API do konfiguracji:

Umieszczaj tokeny tylko w nagłówkach połączenia MCP — nigdy w argumentach narzędzi ani promptach.

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

Jak uzyskać token API

Wywołaj endpoint logowania z danymi uwierzytelniającymi:

curl -X POST https://api.miliexpress.com/api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Odpowiedź będzie zawierać token dostępu:

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "token_type": "Bearer",
  "expires_at": "2026-02-20 00:00:00"
}

Użyj wartości access_token w nagłówku Authorization konfiguracji MCP.

Model bezpieczeństwa agentów

User MCP jest dla least privilege. Twórz tokeny z profilem MCP (domyślnie ops tylko odczyt) lub nagłówkami.

Profile (X-MCP-Profile)

Nazwane pakiety scope. Preferuj ops-readonly lub support dla nienadzorowanych agentów.

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <ops-readonly-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

Opcjonalne nagłówki

Potwierdzenie wysokiego ryzyka

Te narzędzia wymagają confirm=true przy tools/call (lub kolejki zatwierdzeń):

• cancel_order
• bulk_create_orders
• reroute_to_address
• build_route
• hold_order
• release_order
• approve_pending_write
• bulk_create_orders_async
• get_shipping_detail
• download_shipping_label
• cancel_shipping_label
• submit_shipping_information
• end_of_day
• uniorder_cancel
• uniorder_purchase_label
• uniorder_create_batch
• uniorder_create_batch_async
• pay_shipping_order
• cancel_shipping_order
• pay_storage_order
• cancel_storage_order
• pay_shipout
• cancel_shipout

Kolejka zatwierdzeń ludzkich

Nienadzorowani agenci proponują zapisy; człowiek zatwierdza.

1. Agent: propose_write lub X-MCP-Require-Approval: 1
2. Człowiek: MCP Approvals w aplikacji lub list_pending_approvals
3. Człowiek: approve_pending_write z confirm=true lub reject_pending_write

Ścieżka UI web (wymagane logowanie): /mcp-approvals

Uwierzytelnianie Developer MCP

Preferuj Authorization: Bearer na połączeniu. api_token w toolu jest przestarzały i kończy się po 2026-12-31.

Dostępne narzędzia

Następujące narzędzia są obecnie dostępne na serwerze MCP: 93 żywych narzędzi z katalogu serwera

Ta tabela jest generowana z UserMcpToolCatalog w czasie żądania i jest zsynchronizowana z tools/list.

Konfiguracja dla klienta

Wybierz poniżej swojego klienta AI, aby uzyskać dostosowane instrukcje konfiguracji:

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "mili-express": {
      "serverUrl": "https://api.miliexpress.com/mcp"
    }
  }
}

Szczegóły techniczne

• Protokół: JSON-RPC 2.0
• Transportu: HTTP POST (Streamable HTTP)
• Limit szybkości: 60 żądań na minutę
• Typ zawartości: application/json
• Punkt końcowy: https://api.miliexpress.com/mcp
• Wersje protokołu: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
  Oba pokolenia protokołu są obsługiwane pod tym samym punktem końcowym: klienci rozpoczynający od uzgodnienia initialize oraz klienci bezstanowi, którzy deklarują wersję w każdym żądaniu. Serwer nigdy nie wydaje identyfikatora sesji.
• Wykrywanie OAuth: https://api.miliexpress.com/.well-known/oauth-protected-resource
  Żądanie bez uwierzytelnienia zwraca 401 z nagłówkiem WWW-Authenticate wskazującym dokument metadanych chronionego zasobu.