Permitir acesso de agente de IA de terceiros ao seu servidor MCP

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 orienta você na integração do Logto com seu servidor MCP usando mcp-auth e o SDK oficial do MCP v2, permitindo que agentes de IA de terceiros autentiquem usuários com seu consentimento e acessem seu servidor MCP com segurança.

Você aprenderá como:

Configurar o Logto como o servidor de autorização para seu servidor MCP.
Integrar agentes de IA de terceiros, seja registrando aplicativos de terceiros ou habilitando aplicativo dinâmico para que qualquer agente possa se conectar sem pré-registro.
Configurar uma ferramenta “whoami” em seu servidor MCP para retornar as reivindicações de identidade do usuário atual.
Testar o fluxo com um agente de IA de terceiros (cliente MCP).

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

Autenticar usuários em seu tenant Logto, com consentimento do usuário para agentes de IA de terceiros.
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".

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.

Diferença entre agente de IA de terceiros (cliente MCP) e seu próprio cliente MCP

Vamos analisar um exemplo. Imagine que você é um desenvolvedor executando um servidor MCP para gerenciar acesso e automação de e-mails.

Aplicativo de e-mail oficial (Seu próprio cliente MCP)

Você fornece um aplicativo de e-mail oficial para os usuários lerem e gerenciarem seus e-mails.
Como funciona: O aplicativo de e-mail oficial conecta-se ao seu servidor MCP usando o Logto para autenticar usuários. Quando Alice faz login, ela automaticamente obtém acesso aos seus e-mails, sem necessidade de telas de permissão extras, já que é seu aplicativo confiável.

Agente de IA de terceiros (Cliente MCP de terceiros)

Você está construindo um ecossistema em torno do seu servidor MCP, então outro desenvolvedor cria o “SmartMail AI” (um assistente de IA que pode resumir e-mails e agendar reuniões automaticamente), integrando-o como um cliente de terceiros.
Como funciona: O SmartMail AI (cliente MCP de terceiros) deseja acessar os e-mails do usuário via seu servidor MCP. Quando Alice faz login no SmartMail AI usando sua conta:
- Ela vê uma tela de consentimento, solicitando permissão para o SmartMail AI ler seus e-mails e calendário.
- Alice pode permitir ou negar esse acesso.
- Somente os dados aos quais ela consentiu são compartilhados com o SmartMail AI, e o SmartMail AI não pode acessar dados adicionais sem novo consentimento explícito.

Esse controle de acesso (permissão) garante a segurança dos dados do usuário, mesmo que seu servidor MCP gerencie todos os dados, aplicativos de terceiros como o SmartMail AI só podem acessar o que o usuário permitiu explicitamente. Eles não podem contornar esse processo, pois ele é imposto pela sua implementação de controle de acesso no servidor MCP.

Resumo

Tipo de cliente	Exemplo	Consentimento necessário?	Quem controla?
Aplicativo de e-mail oficial	Seu próprio aplicativo de e-mail	Não	Você (o desenvolvedor)
Agente de IA de terceiros	Assistente SmartMail AI	Sim	Outro desenvolvedor

nota:

Se você deseja integrar seu servidor MCP com seu próprio agente de IA ou aplicativo, consulte o guia Habilitar autenticação para seus aplicativos com MCP usando Logto.

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. O agente de IA de terceiros será usado 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 agente de IA de terceiros no Logto

Para permitir que o agente de IA de terceiros acesse seu servidor MCP, você precisa configurar um aplicativo de terceiros no Logto. Este aplicativo será usado para representar o agente de IA e obter as credenciais necessárias para autenticação e autorização.

O que é um aplicativo de terceiros?:

Um aplicativo de terceiros é um aplicativo criado por desenvolvedores externos (que não são os proprietários do recurso) e que precisa do consentimento do usuário para acessar recursos protegidos. Diferente dos aplicativos de primeira parte (seus próprios aplicativos), aplicativos de terceiros exibem uma tela de consentimento solicitando que os usuários aprovem permissões específicas antes de acessar seus dados. Isso garante que os usuários tenham controle sobre quais dados compartilham com serviços externos.

Para saber mais, veja Aplicativos de terceiros.

Existem três maneiras de integrar agentes de IA:

Criar manualmente o aplicativo no Console, para testes ou alguns agentes conhecidos.
Construir um serviço de registro usando a Management API, se você quiser controlar quem recebe credenciais.
Habilitar aplicativo dinâmico, se qualquer agente puder se conectar e você não quiser uma etapa de registro.

Permitir que desenvolvedores criem aplicativos de terceiros no Logto

Se você está construindo um marketplace ou deseja permitir que desenvolvedores criem aplicativos de terceiros no Logto, pode utilizar a Logto Management API para criar aplicativos de terceiros programaticamente. Isso permite que desenvolvedores registrem seus aplicativos e obtenham as credenciais necessárias para autenticação.

Você precisará hospedar seu próprio serviço para lidar com o processo de registro do cliente. Esse serviço irá interagir com a Logto Management API para criar aplicativos de terceiros em nome dos desenvolvedores.

Alternativamente, você pode criar manualmente aplicativos de terceiros no Logto Console para se familiarizar com o processo.

Permitir que qualquer agente de IA se conecte sem pré-registro

Em um ecossistema MCP aberto, geralmente você não conhece os agentes com antecedência. Aplicativo dinâmico remove a etapa de registro: o agente usa uma URL HTTPS pública que serve seu próprio documento de metadados de cliente como seu client_id, e o Logto resolve isso quando a solicitação de autorização chega.

Você ainda controla o que os agentes podem solicitar através das permissões concedidas ao aplicativo dinâmico, e toda autorização passa pela tela de consentimento do usuário.

Criar manualmente um aplicativo de terceiros no Logto

Você pode criar manualmente um aplicativo de terceiros no Logto Console para fins de teste ou integrações pontuais. Isso é útil quando você deseja testar rapidamente a integração sem implementar um fluxo completo de registro de cliente.

Faça login no seu Logto Console.
Vá em Aplicativos → Criar aplicativo → Aplicativo de terceiros -> OIDC.
Preencha o nome do aplicativo e outros campos obrigatórios, depois clique em Criar aplicativo.
Clique na guia Permissões para conceder permissões ao aplicativo:
- Seção Usuário: permissões de dados do usuário como profile e email, para reivindicações básicas de identidade.
- Seção Recurso de API (API resource): permissões (escopos) dos recursos de API que você definiu no Logto, por exemplo, o recurso de API que representa seu servidor MCP.
- Seção Organização (Organization): permissões de organização, se você usar organizações do Logto.
No aplicativo de terceiros, configure os escopos para solicitar as permissões que você concedeu, por exemplo, openid profile email mais os escopos dos recursos de API.

Nota: openid é obrigatório para OIDC. Para receber um token de acesso vinculado a um recurso de API, o aplicativo também deve incluir o parâmetro resource na solicitação de autorização. Clientes MCP que seguem a especificação MCP mais recente fazem isso automaticamente com base nos metadados do recurso protegido.
Configure o redirect URI do seu aplicativo de terceiros conforme necessário. Lembre-se de atualizar o redirect URI também no Logto.

Por trás dos bastidores, um aplicativo de terceiros é um cliente padrão OAuth 2.0 / OIDC. Isso significa que você (ou o desenvolvedor de terceiros) pode usar qualquer biblioteca ou framework OAuth 2.0 / OIDC para integrar com o Logto.

Algumas coisas para ter em mente:

Ao criar um aplicativo de terceiros, selecione o tipo de aplicativo apropriado com base na arquitetura do app:
- Web tradicional: Usa segredo do cliente para autenticação.
- Aplicativo de página única / Nativo: Usa PKCE para autorização segura sem um segredo do cliente.
A maioria dos nossos guias de início rápido são escritos para aplicativos de primeira parte, mas você ainda pode usá-los como referência para integração de aplicativos de terceiros.
A principal diferença é que aplicativos de terceiros exibirão uma tela de consentimento (Consent screen), solicitando permissão explícita dos usuários para acessar seus dados.

Veja Aplicativos de terceiros para o guia completo de integração.

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:

Faça login no seu Logto Console.
Vá para Recursos de API (API resources) → Criar recurso de API (Create API resource).
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

Inicie o servidor MCP.
Conecte o agente de IA de terceiros ao seu servidor MCP e invoque a ferramenta whoami.
O agente recebe uma resposta 401 Não autorizado, descobre o Logto através dos metadados de recurso protegido do servidor MCP e redireciona o usuário para o Logto para autenticação.
O usuário faz login e revisa a tela de consentimento, que lista as permissões solicitadas pelo agente, e então aprova (ou nega) o acesso.
O agente recebe um token de acesso JWT vinculado ao público e o utiliza para invocar a ferramenta novamente.
O servidor MCP verifica o token de acesso contra o JWKS do Logto e retorna as reivindicações de identidade verificadas para o agente.

Leitura adicional

Seu servidor MCP agora verifica tokens de acesso recebidos de agentes de IA de terceiros. Como próximo passo, aprenda como ele pode chamar suas APIs de negócios downstream com segurança 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

Diferença entre agente de IA de terceiros (cliente MCP) e seu próprio cliente MCP​

Pré-requisitos​

Entendendo a arquitetura​

Configurar agente de IA de terceiros no Logto​

Permitir que desenvolvedores criem aplicativos de terceiros no Logto​

Permitir que qualquer agente de IA se conecte sem pré-registro​

Criar manualmente um aplicativo de terceiros no Logto​

Configurar o servidor MCP​

Criar o projeto e instalar dependências​

Registrar o servidor MCP como um recurso de API​

Configurar o MCP Auth com Logto​

Implementar a ferramenta "whoami"​

Conectar o servidor​

Testar a integração​

Leitura adicional​

Diferença entre agente de IA de terceiros (cliente MCP) e seu próprio cliente MCP

Pré-requisitos

Entendendo a arquitetura

Configurar agente de IA de terceiros no Logto

Permitir que desenvolvedores criem aplicativos de terceiros no Logto

Permitir que qualquer agente de IA se conecte sem pré-registro

Criar manualmente um aplicativo de terceiros no Logto

Configurar o servidor MCP

Criar o projeto e instalar dependências

Registrar o servidor MCP como um recurso de API

Configurar o MCP Auth com Logto

Implementar a ferramenta "whoami"

Conectar o servidor

Testar a integração

Leitura adicional