Assistentes de IA (MCP)

A WeShipYou tem um servidor Model Context Protocol (MCP), para que um assistente de IA use a WeShipYou em nome de um usuário que entrou na conta. O assistente nunca vê uma senha: o usuário o aprova numa página da WeShipYou ou no app da WeShipYou, o assistente recebe seu próprio token OAuth e a conexão pode ser revogada a qualquer momento.

Endereços do servidor#

Todo o resto (onde entrar, como se registrar) é descoberto a partir do endereço. Não há chave de API nem segredo de cliente para colar em lugar nenhum.

O que um assistente de cliente pode fazer#

Com o servidor de conta, um assistente pode responder perguntas como "onde está o meu pacote?", "o que há no meu armário?" ou "quanto tenho na carteira?", e pode preparar isto para você:

• pagar um envio que aguarda pagamento;
• cancelar um envio;
• aprovar e pagar um pedido da loja que aguarda a sua aprovação;
• enviar pacotes que estão no seu armário (para um destinatário salvo, se você indicar um).

Deixe um assistente concluir ações por você#

Se preferir não abrir o app toda vez, você pode deixar um assistente concluir algumas ações sozinho. No app, abra Configurações → Assistentes conectados e ative, para esse assistente, qualquer uma de:

• Pagar envios;
• Enviar pacotes do armário para destinatários salvos (um destinatário novo é sempre adicionado no app);
• Aprovar e pagar pedidos da loja;
• Cancelar envios ainda não entregues à transportadora (um envio que a transportadora já tem sempre vai para o app).

Ativar uma pede seu Face ID, sua digital ou a senha do celular. Depois disso, o assistente ainda diz no chat o que vai fazer e quanto custa, e só faz depois do seu sim. Ele paga só com sua carteira (saldo e pontos, nunca com cartão). Se a carteira não cobrir, ou o preço subiu em relação ao que você aceitou, a solicitação vai para o app. Cada ação concluída envia um comprovante e aparece em Feito pelos seus assistentes. Você pode desativar cada ação quando quiser, sem nenhuma verificação.

Pague menos pelos envios#

O assistente também ajuda você a escolher antes de enviar:

• cota seus pacotes do armário para um destinatário salvo com cada serviço, depois dos cupons que se aplicam;
• compara enviá-los juntos com enviá-los um por um;
• avisa quando um pouco mais de peso libera um cupom, e qual pacote pronto do seu armário o adiciona;
• confere o que o destino permite em um envio (peso e valor por volume, quantidades por categoria, pontos de alfândega onde se aplicam);
• lista os cupons que você pode usar.

Essas respostas não mudam nada na sua conta. Alguns destinos também limitam o que um destinatário pode receber em um período; isso é conferido quando o envio é criado.

O assistente nunca pede a sua senha nem números de cartão, e não pode mudar o seu perfil, endereços ou formas de pagamento. Para ver ou desconectar seus assistentes, abra Configurações → Assistentes conectados no app, ou Conta → Assistentes conectados no site.

Assistentes com tela de conectores#

No ChatGPT, Claude (web, desktop ou celular), Gemini ou Grok, adicione um conector personalizado (também chamado de app personalizado, plugin ou servidor MCP), cole o endereço e escolha OAuth se for perguntado. Deixe vazios os campos de ID e segredo do cliente. Uma página da WeShipYou abre: confira que ela mostra o seu usuário e toque em Conectar.

Assistentes sem navegador (código de acesso)#

Um bot de chat (por exemplo no Telegram) ou um assistente que roda num servidor não consegue abrir uma página de login para você. Em vez disso, ele mostra um código como BCDF-GHJK e um link:

1. Abra o link, ou no app da WeShipYou vá em Configurações → Assistentes conectados → Conectar com um código.
2. Confira o nome do assistente e o que ele poderá fazer.
3. Toque em Aprovar. O assistente continua sozinho.

Apps configurados por arquivo#

Apps de desktop e de linha de comando leem o servidor de um arquivo JSON ou de um comando. Na primeira conexão, eles abrem a página de aprovação da WeShipYou no seu navegador. Os exemplos usam o servidor de conta; a equipe de personal shopper usa https://weshipyou.com/api/mcp.

Cursor (~/.cursor/mcp.json, ou .cursor/mcp.json num projeto):

{
  "mcpServers": {
    "weshipyou": {
      "url": "https://weshipyou.com/api/mcp/account"
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "weshipyou": {
      "type": "http",
      "url": "https://weshipyou.com/api/mcp/account"
    }
  }
}

Claude Code:

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

Claude Desktop pelo arquivo de configuração (claude_desktop_config.json), que precisa do Node.js para a ponte mcp-remote. Se você adicionar o servidor em Configurações → Conectores, não precisa instalar nada:

{
  "mcpServers": {
    "weshipyou": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://weshipyou.com/api/mcp/account"]
    }
  }
}

Construir seu próprio cliente#

Qualquer cliente MCP que suporte o transporte Streamable HTTP e OAuth 2.1 pode se conectar. O fluxo é o que a especificação do MCP descreve:

1. Chame o servidor sem token. Ele responde 401 com o cabeçalho WWW-Authenticate: Bearer resource_metadata="…".
2. Leia os metadados do recurso protegido (RFC 9728) indicados ali, por exemplo https://weshipyou.com/.well-known/oauth-protected-resource/api/mcp/account. Eles nomeiam o servidor de autorização, https://weshipyou.com/api.
3. Leia os metadados do servidor de autorização (RFC 8414) em https://weshipyou.com/.well-known/oauth-authorization-server/api: os endpoints de autorização, token, registro, revogação e autorização de dispositivo.
4. Registre o seu cliente (RFC 7591, registro dinâmico de clientes) com POST https://weshipyou.com/api/oauth/register. É um cliente público: sem segredo, token_endpoint_auth_method é none.
5. Envie o usuário ao endpoint de autorização com PKCE (code_challenge_method=S256, obrigatório) e resource com o endereço do servidor (RFC 8707), por exemplo resource=https://weshipyou.com/api/mcp/account. O usuário entra e aprova numa página da WeShipYou.
6. Troque o código no endpoint de token (envie o mesmo redirect_uri e resource) e chame o servidor com Authorization: Bearer <access_token>.

Uma solicitação de registro:

{
  "client_name": "My assistant",
  "redirect_uris": ["http://127.0.0.1:8765/callback"]
}

URIs de redirecionamento#

O registro mantém só as URIs de redirecionamento que a WeShipYou aceita e recusa a solicitação se não sobrar nenhuma:

• Loopback (http://127.0.0.1, http://localhost, http://[::1]) para apps de desktop e de linha de comando. A porta pode mudar entre logins; o host e o caminho devem ser os registrados.
• Esquemas de app que a WeShipYou permitiu, como cursor://.
• Callbacks https de assistentes que a WeShipYou permitiu (assistentes hospedados como ChatGPT e Claude). Para adicionar um assistente hospedado, fale com o suporte e envie a URL de callback dele.

Acesso com código de dispositivo (RFC 8628)#

Um cliente sem navegador nem callback (um bot num servidor) usa a concessão de autorização de dispositivo no lugar dos passos 5 e 6.

Registre-o só com a concessão de dispositivo; ele não precisa de URI de redirecionamento:

{
  "client_name": "My bot",
  "grant_types": ["urn:ietf:params:oauth:grant-type:device_code"]
}

Peça os códigos com um POST https://weshipyou.com/api/oauth/device_authorization em formulário (client_id, e resource com o endereço do servidor). A resposta:

{
  "device_code": "wsyd_…",
  "user_code": "BCDF-GHJK",
  "verification_uri": "https://weshipyou.com/agent-connect",
  "verification_uri_complete": "https://weshipyou.com/agent-connect?code=BCDF-GHJK",
  "expires_in": 600,
  "interval": 5
}

Mostre ao usuário o user_code e o link verification_uri_complete, e consulte o endpoint de token com grant_type=urn:ietf:params:oauth:grant-type:device_code, device_code e client_id, no máximo a cada interval segundos:

A resposta depois da aprovação é o mesmo par de tokens do passo 6.

Tokens#

Atualize com grant_type=refresh_token e guarde só o token de atualização mais recente: usar um antigo depois desses 30 segundos revoga a conexão inteira. Quando a conexão é revogada, ou o usuário perde o acesso, o servidor responde 401 e o cliente precisa levar o usuário de novo à página de aprovação.

Transporte#

O servidor não guarda estado: envie cada mensagem JSON-RPC com POST para o endereço do servidor e leia a resposta JSON. Não há id de sessão nem fluxo de eventos, então GET e DELETE respondem 405. Chame tools/list para obter as ferramentas e seus esquemas de entrada; as ferramentas se descrevem sozinhas, então não fixe os argumentos delas no código.

No servidor de conta, as ferramentas request_* devolvem um id de solicitação e enviam uma notificação ao usuário; get_request_status informa se o usuário a abriu, recusou ou já concluiu, lido do próprio envio ou pedido. Peça ao usuário que confirme no app; nunca peça dados de cartão.

get_automatic_actions lista as ações que o usuário deixou o seu cliente concluir. Para essas, diga ao usuário o que vai fazer e quanto custa, e depois do sim dele chame a ferramenta request_* com confirmedInChat: true e confirmedTotal (o valor em USD que ele aceitou). A resposta traz então automatic: { ran: true, … } com o valor cobrado, ou ran: false com o motivo pelo qual foi para o app (a carteira não cobre, um envio já entregue à transportadora, …). Um preço acima de confirmedTotal é recusado; cote de novo e pergunte. sendToApp: true sempre envia a solicitação para o app. Nunca envie confirmedInChat sem o sim do usuário para aquela ação exata.

quote_shipping, optimize_shipment, check_destination_limits e find_coupons são somente leitura: cotam com os cupons da conta, comparam enviar junto com um por um, encontram o peso que falta para um cupom e conferem os limites do destino.