Coluna MCP

Visão geral da coluna MCP

Este guia é a coluna MCP Superroute no Developer Center: ambos os servidores, segurança de agentes e catálogo de tools ao vivo.

• User MCP — pedidos, rotas, etiquetas, digests para agentes de ops/suporte — https://api.superlabel.ca/mcp
• Developer MCP — guias, webhooks e APIs de exemplo para integradores — https://api.superlabel.ca/mcp/developer
• Segurança: Bearer na conexão, perfis/scopes, confirm em tools de alto risco
• Fila de aprovação humana (propose_write + /mcp-approvals)

O que é MCP?

O Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA como Claude, Cursor e ChatGPT interajam com ferramentas e serviços externos. Ele permite que sua IA execute ações reais — como rastrear um pacote — diretamente na conversa.

Ao configurar o servidor MCP do Superroute, seu assistente de IA obtém acesso a ferramentas logísticas sem sair do seu fluxo de trabalho.

Dois servidores MCP

Use o servidor certo. Não dê o Developer com acesso total a agentes sem supervisão.

Início rápido

Ferramentas públicas como rastreamento de pacotes funcionam sem autenticação. Adicione esta configuração ao seu cliente MCP:

{
  "mcpServers": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp"
    }
  }
}

Acesso autenticado

Para usar ferramentas que requerem permissões de usuário, adicione seu token Bearer da API à configuração:

Coloque tokens apenas nos headers da conexão MCP — nunca em argumentos de tools ou prompts.

{
  "mcpServers": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

Como obter um token de API

Chame o endpoint de login com suas credenciais:

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

A resposta incluirá seu token de acesso:

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

Use o valor access_token no cabeçalho Authorization da sua configuração MCP.

Modelo de segurança do agente

User MCP é feito para menor privilégio. Crie tokens com perfil MCP (padrão ops somente leitura) ou envie headers.

Perfis (X-MCP-Profile)

Pacotes de scopes nomeados. Prefira ops-readonly ou support para agentes sem supervisão.

{
  "mcpServers": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp",
      "headers": {
        "Authorization": "Bearer <ops-readonly-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

Headers opcionais

Confirmação de alto risco

Estas tools exigem confirm=true em tools/call (ou a fila de aprovação):

• cancel_order
• bulk_create_orders
• reroute_to_address
• build_route
• hold_order
• release_order
• approve_pending_write

Fila de aprovação humana

Agentes sem supervisão devem propor gravações; humanos aprovam.

1. Agente: propose_write ou X-MCP-Require-Approval: 1
2. Humano: MCP Approvals no app ou list_pending_approvals
3. Humano: approve_pending_write com confirm=true ou reject_pending_write

Caminho da UI web (login necessário): /mcp-approvals

Autenticação Developer MCP

Prefira Authorization: Bearer na conexão. api_token por tool está obsoleto e corta após 2026-12-31.

Ferramentas disponíveis

As seguintes ferramentas estão atualmente disponíveis no servidor MCP: 47 tools ao vivo do catálogo do servidor

Esta tabela é gerada do UserMcpToolCatalog em tempo de requisição e fica sincronizada com tools/list.

Configuração por cliente

Selecione seu cliente de IA abaixo para instruções de configuração personalizadas:

{
  "mcpServers": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp"
    }
  }
}

{
  "mcpServers": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

{
  "mcpServers": {
    "super-label": {
      "type": "url",
      "url": "https://api.superlabel.ca/mcp"
    }
  }
}

{
  "mcpServers": {
    "super-label": {
      "serverUrl": "https://api.superlabel.ca/mcp"
    }
  }
}

Detalhes técnicos

• Protocolo: JSON-RPC 2.0
• Transporte: HTTP POST (Streamable HTTP)
• Limite de taxa: 60 requisições por minuto
• Tipo de conteúdo: application/json
• Ponto final: https://api.superlabel.ca/mcp
• Versões do protocolo: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
  As duas gerações do protocolo são servidas no mesmo endpoint: clientes que abrem com um handshake initialize e clientes sem estado que declaram a versão em cada pedido. Nunca é emitido um identificador de sessão.
• Descoberta OAuth: https://api.superlabel.ca/.well-known/oauth-protected-resource
  Um pedido não autenticado responde 401 com um cabeçalho WWW-Authenticate que aponta para o documento de metadados do recurso protegido.