Guia de integração MCP

Retorno do login de autorização

Instale o SDK:

pnpm add mcp-auth-web

Ambientes da API (engineUrl é o endereço base, sem caminho):

Teste: https://aim-api-test.proton-system.com
Produção: https://aim-api.proton-system.com

URL completa de retorno: https://xxx.com/openapi/v1/mcp/authorization/callback

O SDK adiciona o caminho automaticamente.

Retorne as credenciais após o login:

import { createMcpAuthClient } from 'mcp-auth-web'

const mcpAuth = createMcpAuthClient({
  engineUrl: 'https://aim-api-test.proton-system.com',
})

mcpAuth.complete({
  Authorization: `Bearer ${token}`,
})

Quando o login falhar ou o usuário cancelar:

mcpAuth.fail({ code, message })
mcpAuth.cancel()

A partir de mcp-auth-web@0.3.1, getMcpAuthErrorMessage(error) fornece mensagens padrão seguras em chinês mantidas pelo SDK. A interface as exibe; use os códigos para personalização ou tradução. Capture exceções de complete(), fail() e cancel(). Não chame fail() incondicionalmente no catch de complete() nem exponha credenciais ou URLs de autorização dos erros originais.

import { getMcpAuthErrorMessage } from 'mcp-auth-web'

try {
  mcpAuth.complete({ Authorization: `Bearer ${token}` })
} catch (error) {
  message.error(getMcpAuthErrorMessage(error))
}

engineUrl é o endereço do Engine fornecido pela plataforma. complete recebe diretamente os Headers de credencial usados pelo MCP. O SDK lê exp do JWT Bearer em Authorization e gera expiresAt automaticamente, portanto não é necessário informar a validade.

O SDK escolhe automaticamente o callback HTTPS ou a janela de autorização existente do App. O mcp-auth-web@0.3.0 altera o formato de entrada de complete; ao atualizar, remova o invólucro headers e o expiresAt informado manualmente. Sem engineUrl, a janela de autorização existente do App continua sendo usada.

Se o método retornar false, a página atual não tem uma forma disponível de retornar a autorização:

if (!mcpAuth.isAvailable()) {
  message.error('Este ambiente não oferece suporte ao retorno da autorização')
}

Para verificar, inicie a autorização no App e conclua o login. Voltar ao App com “Autorizado” confirma a integração. Em produção, o login e o Engine exigem HTTPS acessível pelo dispositivo e certificado válido. Não registre credenciais nem URLs de autorização.

Anotações gerais de risco do Tool

Tool de leitura:

annotations: {
  readOnlyHint: true
}

Tool de escrita:

annotations: {
  destructiveHint: true
}

Tipos de Tool

1. Tool de lista

Quando um Tool retorna candidatos para o usuário selecionar antes de preencher outro parâmetro de Tool, adicione este objeto na raiz de outputSchema:

outputSchema: {
  type: "object",
  properties: {...}, // opcional
  "x-prerequisiteCandidate": {
    itemsPath: "data",
    valuePath: "id",
    labelPath: "name"
  }
}

Os três campos significam:

itemsPath: onde a lista de candidatos fica no resultado do Tool.
valuePath: qual campo de cada candidato será preenchido como valor final.
labelPath: qual campo de cada candidato será exibido ao usuário.

Por exemplo, o Tool retorna:

{
  "data": [
    { "id": "1", "name": "Loja A" },
    { "id": "2", "name": "Loja B" }
  ]
}

Então:

itemsPath: "data" indica que a lista de candidatos é o array data.
valuePath: "id" indica que o id selecionado será preenchido no Tool de destino.
labelPath: "name" indica que o cartão de seleção exibirá o name.

Lista de verificação