Servidor MCP

A Pilot Status oferece um servidor oficial de Model Context Protocol (MCP) que expõe a API pública /v1 como ferramentas MCP. Agentes de IA e clientes LLM podem usá-lo para enviar mensagens, consultar conversas, gerenciar números, templates, webhooks, grupos e chamadas de voz — diretamente do contexto do modelo.

Conector hospedado

O servidor usa o transporte streamable HTTP e roda como um conector hospedado em:

https://mcp.pilotstatus.com.br/mcp

Adicione-o como um Conector Personalizado no claude.ai (Configurações → Conectores → Adicionar conector personalizado). O claude.ai executa o login OAuth 2.1 (SSO da Pilot Status) — nenhuma chave de API é compartilhada com o cliente. Durante a etapa de consentimento você aprova o acesso ao tenant inteiro ou concede apenas números específicos; uma concessão por número restringe cada ferramenta a esses números. Qualquer cliente MCP que suporte conectores OAuth personalizados pode conectar da mesma forma. Clientes configurados por arquivo podem, em vez disso, enviar uma chave ps_* no header x-api-key:

{
  "mcpServers": {
    "pilot-status": {
      "type": "http",
      "url": "https://mcp.pilotstatus.com.br/mcp",
      "headers": { "x-api-key": "ps_your_key_here" }
    }
  }
}

Autenticação

Método	Como
OAuth 2.1	`Authorization: Bearer <token>` — tratado automaticamente pelo conector Claude hospedado
Chave de API	header `x-api-key` com uma chave `ps_*`

Use uma chave com escopo de número para ferramentas que operam em um número específico (mensagens, conversas, grupos); chaves com escopo de tenant são necessárias para ferramentas de tenant como api_keys_list e numbers_list.

Auto-hospedado

O servidor é publicado como @pilot-status/mcp-server no npm e pode ser executado localmente:

npx @pilot-status/mcp-server

Forneça sua chave de API ps_* através do header x-api-key (modo HTTP) ou por configuração de ambiente, dependendo do seu cliente MCP.

Ferramentas disponíveis (94)

Área	Ferramentas
Mensagens	`messages_send`, `message_get`, `messages_list`, `messages_history`, `messages_cancel`, `messages_group`, `messages_unread`, `messages_mark_read`, `messages_typing`, `conversations_list`
Origens de anúncio (CTWA)	`referrals_list`, `referrals_summary`
Webhooks	`webhooks_list`, `webhook_get`, `webhooks_create`, `webhooks_update`, `webhooks_delete`, `webhook_events`
Chatwoot	`chatwoot_get`, `chatwoot_connect`, `chatwoot_update`, `chatwoot_disconnect`, `chatwoot_test`
Replay de histórico no Chatwoot	`chatwoot_history_replay`, `chatwoot_history_replay_get`, `chatwoot_history_replay_cancel`
Grupos	`groups_list`, `groups_create`, `group_info`, `group_participants_add`, `group_participants_remove`, `group_participants_promote`, `group_participants_demote`, `group_invite`, `group_pin`
Canais	`newsletters_list`
Números	`numbers_list`, `numbers_get`, `numbers_create`, `numbers_status`, `numbers_connect`, `numbers_delete`, `numbers_restore`, `numbers_purge`, `numbers_pay`, `numbers_remote_pairing`, `numbers_check`, `numbers_settings_update`
Templates	`templates_list`, `templates_get`, `templates_create`, `templates_update`, `templates_delete`
Flows	`flows_list`, `flows_create`, `flows_update`, `flows_json_upload`, `flows_publish`, `flows_deprecate`, `flows_delete`, `flows_responses_list`, `flows_endpoint_key_get`, `flows_endpoint_key_rotate`
Chamadas de voz	Meta e web: `call_initiate`, `calls_list`, `call_get`, `call_accept`, `call_reject`, `call_terminate`; só Meta: `call_settings_get`, `call_settings_update`, `call_enable`, `call_permission_get`, `call_permission_request`; só web (não oficial): `call_play`, `call_realtime_session`
Conta	`api_keys_list`, `api_keys_regenerate_number`, `subscription_extra_numbers_get`, `subscription_extra_numbers_add`, `subscription_extra_numbers_remove`, `subscription_extra_numbers_cancel_scheduled`, `billing_checkout`, `branding_get`, `branding_upsert`, `analytics_dashboard`, `media_get`
Preços da Meta	`meta_pricing_get`
Workspace	`workspace_get`, `workspace_members_list`, `workspace_members_invite`, `workspace_members_resend`, `workspace_members_update`, `workspace_members_remove`

Notas:

templates_create/templates_update exigem o objeto examples (uma amostra real por variável; ausente → 400 TEMPLATE_EXAMPLES_REQUIRED) e aceitam headers de mídia apenas por URL — base64 é exclusivo do REST.
messages_send suporta os três modos de envio: templateId, text ou mídia direta (media + mediaType; use mediaType: "voice" para nota de voz em qualquer número — "audio" chega como arquivo de áudio em números oficiais e como nota de voz em números não oficiais).
Mídia recebida: em números META, passe media.id para media_get; em números não oficiais (Pilot Status web), use media.url diretamente.
numbers_delete é um soft delete de 30 dias, desfeito com numbers_restore. numbers_purge exclui um número de forma permanente e irreversível; com token OAuth, só o OWNER do workspace pode chamá-la.
numbers_pay paga a cobrança pendente do número extra de um número e libera o envio por ele (POST /v1/numbers/{id}/pay) — havendo saldo ou cartão, cobra na hora. Exige uma chave com escopo de tenant com billing:manage; com token OAuth, só o OWNER do workspace tem essa permissão.
Rotas baseadas em token (endpoints públicos de remote-pairing, emissão de sessão de embed) são excluídas da lista de ferramentas porque usam um fluxo de autenticação diferente.

Exemplo de chamada de ferramenta

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 2,
  "params": {
    "name": "messages_send",
    "arguments": {
      "templateId": "onboarding-test",
      "destinationNumber": "+5511999999999",
      "variables": { "name": "John" }
    }
  }
}

Erros comuns

401 — chave de API ausente ou inválida.
403 — chave com escopo de tenant em uma ferramenta com escopo de número (ou vice-versa), ou uma ferramenta fora de uma concessão por número.
400 — argumentos de ferramenta inválidos (validados contra o schema da API subjacente).

Primeiros Passos

Conceitos

Guias

Integrações

Painel

Confiança & Dados

Planos & Suporte

Changelog

Conector hospedado

Autenticação

Auto-hospedado

Ferramentas disponíveis (94)

Exemplo de chamada de ferramenta

Erros comuns

Relacionados

​Conector hospedado

​Autenticação

​Auto-hospedado

​Ferramentas disponíveis (94)

​Exemplo de chamada de ferramenta

​Erros comuns

​Relacionados

Conector hospedado

Autenticação

Auto-hospedado

Ferramentas disponíveis (94)

Exemplo de chamada de ferramenta

Erros comuns

Relacionados