MCP Server

Conecte a Routal ao Claude, ChatGPT ou qualquer cliente MCP — importe paradas, otimize planos e consulte analytics operacionais conversando com o seu assistente de IA.

A Routal oferece um servidor MCP hospedado. Conecte-o uma vez e o seu assistente de IA pode listar os seus projetos, importar paradas, criar e otimizar planos e responder perguntas sobre a sua operação — usando a sua própria conta Routal, com as suas próprias permissões. Um único servidor funciona com qualquer cliente MCP: Claude, ChatGPT, Claude Code, Cursor e qualquer outro que fale o protocolo. Esta página é o guia de setup para todos eles.

Dados de conexão


URL do servidor	`https://api.routal.com/mcp`
Transporte	Streamable HTTP
Autenticação	OAuth 2.1 — faça login com a sua conta Routal quando o cliente pedir
Credenciais necessárias	Nenhuma. Sem API key, sem configuração — o fluxo OAuth cuida de tudo

O servidor suporta dynamic client registration e PKCE, então qualquer cliente MCP compatível pode conectar sem credenciais pré-registradas. O assistente age como o seu usuário Routal: vê os mesmos projetos, planos e paradas que você vê em planner.routal.com, e nada mais.

Diretório vs. URL manual

Se a Routal aparecer no diretório de conectores ou apps do seu cliente, conecte por lá — um clique, o mesmo servidor. Os passos abaixo são para conectar por URL diretamente, o que funciona hoje em qualquer cliente.

Conectar pelo Claude

No claude.ai (web, desktop ou mobile — requer um plano pago do Claude):

Abra Settings → Connectors.
Clique em Add custom connector.
Cole https://api.routal.com/mcp e clique em Add.
Clique em Connect e faça login com a sua conta Routal quando a janela de OAuth abrir.

Em uma conversa nova as ferramentas da Routal já estão disponíveis — o Claude pede confirmação antes de qualquer ferramenta que escreva dados.

Para o Claude Code, adicione o servidor pelo terminal:

claude mcp add --transport http routal https://api.routal.com/mcp

Depois execute /mcp dentro do Claude Code para completar o login OAuth.

Conectar pelo ChatGPT

No chatgpt.com (web — requer Plus, Pro, Business, Enterprise ou Edu):

Ative o developer mode: Settings → Apps & Connectors → Advanced settings → Developer mode.
Vá em Settings → Apps & Connectors e crie um conector novo:
- Name: Routal
- MCP server URL: https://api.routal.com/mcp
- Authentication: OAuth
Faça login com a sua conta Routal quando a janela de OAuth abrir.
Em uma conversa, abra o menu de ferramentas do composer e ative o conector da Routal.

Os nomes exatos dos menus do ChatGPT mudam entre versões — se você não vir essas opções, consulte o guia de developer mode da OpenAI.

Conectar por qualquer outro cliente MCP

Funciona qualquer cliente que suporte Streamable HTTP com OAuth. A forma genérica de configuração:

{
  "mcpServers": {
    "routal": {
      "type": "http",
      "url": "https://api.routal.com/mcp"
    }
  }
}

Cursor, VS Code, Windsurf e a maioria dos frameworks de agentes aceitam exatamente isso no arquivo de configuração MCP, e disparam o login OAuth no primeiro uso.

O que o assistente pode fazer

O servidor expõe 14 ferramentas. As de leitura rodam livremente; clientes bem projetados pedem a sua confirmação antes das quatro que escrevem.

Descobrir e preparar

Ferramenta	O que faz
`list_projects`	Lista os projetos que a sua conta pode acessar.
`get_import_schema`	Quais campos e constraints um projeto aceita — time windows, pickups, peso, custom fields.
`get_organization_resources`	Seu uso vs. os limites da assinatura (usuários, veículos, paradas por plano, créditos de SMS/WhatsApp/geocoding).

Planos, paradas e frota

Ferramenta	O que faz
`create_plan` ✏️	Cria um plano vazio para uma data de execução.
`import_stops` ✏️	Importa até 100 paradas por chamada — geocodifica endereços; suporta time windows, pares pickup+delivery, tarefas do motorista e pacotes por volume.
`search_stops`	Filtra paradas por predicado — status, data de execução, motivo de cancelamento, campos de texto.
`move_stops` ✏️	Move paradas para outro plano ou de volta ao inbox de não atribuídas.
`list_plans`	Resumos paginados de planos com filtros de status, intervalo de datas e texto.
`get_plan`	Detalhe completo de um plano — cada parada, rota e veículo.
`list_vehicles`	A frota do projeto: capacidades, skills, preços, estado habilitado.

Otimizar

Ferramenta	O que faz
`optimize_plan` ✏️	Inicia uma otimização — atribui paradas a veículos, ordena-as, calcula ETAs. Assíncrona.
`get_optimization_status`	Consulta se a otimização ainda está rodando.
`get_last_optimization`	O resultado final — atribuições de rotas, tempos por parada, paradas não atribuídas.

Analisar

Ferramenta	O que faz
`get_analytics`	Séries temporais de paradas, motivos de cancelamento, provas de entrega e planos — agrupadas por dia/semana/mês/trimestre/ano.

✏️ = escreve dados.

Prompts para experimentar

Importe estas paradas em um plano novo para amanhã e otimize-o: [cole linhas da sua planilha]

Quais entregas foram canceladas esta semana e qual foi o motivo mais comum?

Encontre as paradas incompletas de sexta-feira e mova-as para o plano de segunda.

Quão perto estamos dos limites da assinatura? Quero adicionar cinco veículos.

Uma sessão de planejamento típica encadeia as ferramentas por você: o assistente resolve o seu projeto (list_projects), verifica quais campos ele aceita (get_import_schema), cria o plano, importa as paradas em lotes de 100, inicia a otimização, faz polling até terminar e lê as rotas resultantes — incluindo as paradas que o otimizador não conseguiu alocar.

Segurança e acesso a dados

Você autoriza com OAuth, por usuário. O servidor nunca vê uma API key, e o assistente só pode tocar os dados que o seu usuário Routal pode tocar.
Escritas são opt-in. As quatro ferramentas que escrevem são anotadas como tal; Claude e ChatGPT pedem confirmação antes de executá-las. Todo o resto é somente leitura.
Revogue quando quiser. Remova o conector nas configurações do seu cliente e o token de acesso dele para de funcionar.
Os resultados passam pelo seu provedor de IA. O que as ferramentas retornam é processado pelo Claude ou ChatGPT sob as políticas de dados daquele provedor — a mesma consideração de colar os dados você mesmo no chat.

Troubleshooting

Sintoma	Solução
Ferramentas falham com `mcp.error.unauthorized` depois de funcionarem	O token OAuth foi revogado ou expirou. Desconecte e reconecte o conector para fazer login de novo.
A otimização "terminou na hora" mas as rotas não mudaram	A otimização é assíncrona — a chamada inicial retorna imediatamente. Peça ao assistente para consultar o status e ler o resultado quando terminar.
"Já existe uma otimização em andamento"	Uma otimização por plano de cada vez. Espere a atual terminar e tente de novo.
Importar centenas de paradas parece lento	`import_stops` limita a 100 paradas por chamada por design; o assistente faz os lotes automaticamente.
Ferramentas não aparecem no ChatGPT	Atualize o conector em Settings → Apps & Connectors e confira se ele está ativado no menu de ferramentas da conversa.

Ainda travado? Escreva para developers@routal.com. O servidor MCP compartilha o rate limit da API (2.000 requests/min por organização) — veja Rate limits.

On this page