Pular para o conteúdo principal

Ative a autenticação para seus apps com MCP usando Logto

dica:

Explore as soluções de IA do Logto: autenticação (authentication) e autorização (authorization) para servidores MCP, agentes de IA e aplicativos.

Este guia mostra como integrar o Logto ao seu servidor MCP usando mcp-auth e o SDK oficial do MCP v2, permitindo autenticar usuários e ler com segurança sua identidade verificada a partir do token de acesso.

Você aprenderá como:

  • Configurar o Logto como servidor de autorização para seu servidor MCP.
  • Configurar uma ferramenta “whoami” em seu servidor MCP para retornar as reivindicações de identidade do usuário atual.
  • Testar o fluxo com o VS Code (cliente MCP).

Após este tutorial, seu servidor MCP irá:

  • Autenticar usuários em seu tenant Logto.
  • Verificar tokens de acesso JWT emitidos pelo Logto (assinatura, emissor, público e expiração).
  • Retornar as reivindicações de identidade verificadas (sub, iss, aud, etc.) para a invocação da ferramenta "whoami".

Depois de concluir a integração, você pode substituir o VS Code pelo seu próprio cliente MCP, como um aplicativo web, para acessar as ferramentas e recursos expostos pelo seu servidor MCP.

Código de exemplo:

O código de exemplo completo e executável para este guia pode ser encontrado no repositório mcp-auth/js:

  • whoami-express: o servidor "whoami" deste guia, em Node.js com Express.
  • whoami: o mesmo servidor construído com fetch-native (web-standard Request / Response com Hono), implantável no Cloudflare Workers.

Pré-requisitos​

  • Um tenant do Logto Cloud (ou auto-hospedado)
  • Ambiente Node.js >= 20

Entendendo a arquitetura​

  • Servidor MCP: O servidor que expõe ferramentas e recursos para clientes MCP. Seguindo a especificação MCP mais recente, atua como um servidor de recursos OAuth 2.0 que valida tokens de acesso emitidos pelo Logto.
  • Cliente MCP: Um cliente usado para iniciar o fluxo de autenticação e testar a integração. Usaremos o VS Code (com suporte MCP integrado) como cliente neste guia.
  • Logto: Atua como o provedor OpenID Connect (servidor de autorização), gerencia identidades de usuários e emite tokens de acesso JWT vinculados ao público para seu servidor MCP.

Um diagrama de sequência não normativo ilustra o fluxo geral do processo:

nota:

Devido à rápida evolução do MCP, o diagrama acima pode não estar totalmente atualizado. Consulte a documentação do mcp-auth para as informações mais recentes.

Configurar app no Logto​

Seu cliente MCP precisa ser registrado como um aplicativo no Logto para iniciar o fluxo de autorização. Vamos registrar o VS Code como cliente neste guia:

  1. Faça login no seu Console Logto.

  2. Vá para Aplicativos → Criar aplicativo → Criar app sem framework.

  3. Escolha o tipo: Aplicativo nativo.

  4. Preencha o nome do app (por exemplo, "VS Code") e outros campos obrigatórios, depois clique em Criar aplicativo.

  5. Na seção Configurações / URIs de redirecionamento, adicione os seguintes URIs de redirecionamento para o VS Code e salve as alterações:

    http://127.0.0.1
    https://vscode.dev/redirect

  6. Salve e copie o ID do app e o endpoint do emissor.

Configurar o servidor MCP​

Vamos usar o SDK oficial do MCP v2 e o mcp-auth para criar um servidor MCP com uma ferramenta "whoami" que retorna as reivindicações de identidade do usuário atual.

Criar o projeto e instalar dependências​

mkdir mcp-server
cd mcp-server
npm init -y
npm pkg set type="module"
npm pkg set main="whoami.js"
npm pkg set scripts.start="node whoami.js"
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express mcp-auth
  • @modelcontextprotocol/server é o SDK principal do MCP v2, que utiliza Request / Response padrão web.
  • @modelcontextprotocol/express e @modelcontextprotocol/node o adaptam para Express no Node.js.
  • mcp-auth fornece o verificador de token e os metadados de descoberta OAuth para o SDK do MCP.
nota:

O SDK do MCP v2 e o mcp-auth são apenas ESM e requerem Node.js >= 20.

Registrar o servidor MCP como um recurso de API​

A especificação mais recente do MCP exige que os tokens de acesso estejam vinculados ao recurso para o qual foram emitidos (RFC 8707), e o mcp-auth reforça isso: a reivindicação aud do token deve corresponder ao identificador de recurso do seu servidor MCP. No Logto, isso é feito criando um recurso de API cujo indicador corresponda à URL do seu servidor MCP:

  1. Faça login no seu Logto Console.
  2. Vá para Recursos de API (API resources) → Criar recurso de API (Create API resource).
  3. Preencha os detalhes e clique em Criar recurso de API (Create API resource):
    • Nome da API (API name): Insira um nome, por exemplo, "Who am I".
    • Identificador da API (API identifier): Insira http://localhost:3001/. Deve corresponder ao identificador de recurso que configuraremos no servidor MCP.
Barra final no indicador de recurso:

Sempre inclua uma barra final (/) no indicador de recurso. Devido a um bug atual no SDK oficial do MCP, clientes que usam o SDK adicionarão automaticamente uma barra final aos identificadores de recurso ao iniciar solicitações de autenticação. Se o seu indicador de recurso não incluir a barra final, a validação do recurso falhará para esses clientes.

Configurar o MCP Auth com Logto​

Declare seu servidor MCP como um recurso protegido: seu identificador de recurso e o servidor de autorização em que ele confia. Lembre-se de substituir <your-logto-issuer-endpoint> pelo endpoint do emissor que você copiou anteriormente (encontrado na página de detalhes do aplicativo em Endpoints & Credentials, por exemplo, https://my-project.logto.app/oidc).

Em whoami.js:

import { MCPAuth } from 'mcp-auth';

const authIssuer = '<your-logto-issuer-endpoint>';

const mcpAuth = new MCPAuth({
  protectedResourceMetadata: {
    // O identificador do recurso; deve corresponder ao indicador do recurso de API registrado no Logto
    resource: 'http://localhost:3001/',
    // O servidor de autorização confiável por este servidor MCP
    authorizationServer: { issuer: authIssuer, type: 'oidc' },
  },
});

Os metadados do servidor de autorização são buscados sob demanda quando necessário pela primeira vez e armazenados em cache depois disso. A instância MCPAuth verifica tokens de acesso JWT contra o JWKS do Logto — assinatura, emissor, público e expiração são todos validados. Não é necessário verificação manual de tokens.

Implementar a ferramenta "whoami"​

Agora, vamos implementar a ferramenta "whoami" que retorna as reivindicações de identidade do usuário atual a partir do token de acesso verificado. Use getAuthInfo para ler as informações de autenticação que o mcp-auth verificou a partir do contexto de callback da ferramenta.

import { McpServer } from '@modelcontextprotocol/server';
import { getAuthInfo } from 'mcp-auth';

// Função de fábrica para criar uma instância do servidor MCP
// Cada requisição recebe sua própria instância do servidor, mantendo as requisições isoladas
const createMcpServer = () => {
  const mcpServer = new McpServer({
    name: 'WhoAmI',
    version: '0.0.0',
  });

  // Adiciona uma ferramenta ao servidor que retorna as informações do usuário atual
  mcpServer.registerTool(
    'whoami',
    {
      description: 'Obter as informações do usuário atual',
    },
    (context) => {
      const { claims } = getAuthInfo(context);
      return {
        content: [{ type: 'text', text: JSON.stringify(claims) }],
      };
    }
  );

  return mcpServer;
};

Conectar o servidor​

Por fim, sirva os documentos de descoberta OAuth (RFC 9728 / RFC 8414) para que clientes MCP possam encontrar seu servidor de autorização, e proteja o endpoint MCP com o middleware Bearer auth do SDK.

import {
  createMcpExpressApp,
  mcpAuthMetadataRouter,
  requireBearerAuth,
} from '@modelcontextprotocol/express';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createMcpHandler } from '@modelcontextprotocol/server';

const PORT = 3001;

// O handler MCP utiliza Request / Response padrão web; `toNodeHandler` o adapta para Express
const mcpNodeHandler = toNodeHandler(createMcpHandler(createMcpServer));

const app = createMcpExpressApp();

// Sirva os documentos de descoberta OAuth (`/.well-known/...`), públicos por padrão
app.use(mcpAuthMetadataRouter(await mcpAuth.getAuthMetadataOptions()));

app.all(
  '/',
  // Exige um token Bearer válido; as informações de autenticação verificadas fluem para o handler via `req.auth`
  requireBearerAuth(mcpAuth.getBearerAuthOptions()),
  // `createMcpExpressApp` aplica `express.json()`, que consome o stream da requisição, então o
  // corpo já analisado é passado explicitamente
  async (request, response) => mcpNodeHandler(request, response, request.body)
);

app.listen(PORT);

Execute o servidor com:

npm start

Testar a integração​

  1. Inicie o servidor MCP:

    npm start

  2. Conecte o VS Code ao seu servidor MCP:

    1. Pressione Command + Shift + P (macOS) ou Ctrl + Shift + P (Windows / Linux) para abrir a Paleta de Comandos.
    2. Digite MCP: Add Server... e selecione.
    3. Escolha HTTP como tipo de servidor.
    4. Insira a URL do servidor MCP: http://localhost:3001/
    5. Quando o fluxo OAuth começar, o VS Code solicitará o Client ID: cole o ID do app que você copiou anteriormente.
    6. Como é um cliente público sem segredo de app, apenas pressione Enter para pular o segredo.
    7. Complete o fluxo de login em seu navegador.

  3. Após o login, execute a ferramenta whoami no VS Code.

Você deverá ver as reivindicações verificadas do token de acesso, como:

{
  "iss": "https://my-project.logto.app/oidc",
  "sub": "user_XXXX",
  "aud": "http://localhost:3001/",
  "client_id": "<your-app-id>"
}

Leitura adicional​

Seu servidor MCP agora verifica tokens de acesso recebidos. Como próximo passo, aprenda como ele pode chamar com segurança suas APIs de negócios downstream em nome dos usuários, sem repasse de token ou perda de contexto do usuário:

Como um servidor MCP chama sua API em nome dos usuários: uma estratégia de token para produção