Guía de integración MCP

Devolución del inicio de sesión autorizado

Instala el SDK:

pnpm add mcp-auth-web

Entornos API (engineUrl es la dirección base, sin ruta):

Pruebas: https://aim-api-test.proton-system.com
Producción: https://aim-api.proton-system.com

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

El SDK añade la ruta automáticamente.

Devuelve las credenciales después de iniciar sesión:

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

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

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

Si el acceso falla o el usuario cancela:

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

Desde mcp-auth-web@0.3.1, getMcpAuthErrorMessage(error) ofrece mensajes seguros predeterminados en chino mantenidos por el SDK. La interfaz los muestra; los códigos permiten personalizarlos o traducirlos. Capture las excepciones de complete(), fail() y cancel(). No llame incondicionalmente a fail() desde el catch de complete() ni exponga credenciales o URL de autorización de errores sin procesar.

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

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

engineUrl es la dirección de Engine proporcionada por la plataforma. complete recibe directamente los Headers de credenciales que usa tu MCP. El SDK lee exp del JWT Bearer de Authorization y genera expiresAt automáticamente, por lo que no debes enviar la caducidad.

El SDK elige automáticamente el retorno HTTPS o la ventana de autorización existente del App. mcp-auth-web@0.3.0 cambia el formato de entrada de complete; al actualizar, elimina el contenedor headers y el expiresAt enviado manualmente. Sin engineUrl, se sigue usando la ventana de autorización existente del App.

Si el método devuelve false, la página no dispone de una forma de devolver la autorización:

if (!mcpAuth.isAvailable()) {
  message.error('Este entorno no admite la devolución de autorización')
}

Para verificarlo, inicia la autorización en App y completa el acceso. Si vuelves a App y aparece “Autorizado”, la integración funciona. En producción, el acceso y Engine deben usar HTTPS accesible desde el dispositivo y un certificado válido. No registres credenciales ni URLs de autorización.

Anotaciones de riesgo comunes de Tool

Tool de lectura:

annotations: {
  readOnlyHint: true
}

Tool de escritura:

annotations: {
  destructiveHint: true
}

Tipos de Tool

1. Tool de lista

Si un Tool devuelve candidatos para que el usuario elija antes de rellenar otro parámetro de Tool, añade este objeto en la raíz de outputSchema:

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

Los tres campos significan:

itemsPath: ubicación de la lista de candidatos en el resultado del Tool.
valuePath: campo de cada candidato que se rellena como valor final.
labelPath: campo de cada candidato que se muestra al usuario.

Por ejemplo, el Tool devuelve:

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

Entonces:

itemsPath: "data" indica que la lista de candidatos es el array data.
valuePath: "id" indica que el id elegido se rellena en el Tool de destino.
labelPath: "name" indica que la tarjeta de selección muestra el name.

Lista de comprobación