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

Este guia orienta você na integração do Logto com seu servidor MCP usando o mcp-auth, permitindo autenticar usuários e recuperar com segurança suas informações de identidade utilizando o fluxo padrão do OpenID Connect.

Você aprenderá como:

• Configurar o Logto como o 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 um agente de IA de terceiros (cliente MCP).

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

• Autenticar usuários em seu tenant Logto.
• Retornar reivindicações de identidade (sub, username, name, email, etc.) para a invocação da ferramenta "whoami".

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 os usuários. Quando Alice faz login, ela automaticamente tem acesso aos seus e-mails, sem telas extras de permissão, 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 para os quais ela consentiu são compartilhados com o SmartMail AI, e o SmartMail AI não pode acessar nenhum dado adicional sem um 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 apps com MCP usando Logto.

Pré-requisitos

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

Entendendo a arquitetura

• Servidor MCP: O servidor que expõe ferramentas e recursos para clientes MCP.
• 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) e gerencia as identidades dos usuários.

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 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.

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 os 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. Este serviço irá interagir com a Logto Management API para criar aplicativos de terceiros em nome dos desenvolvedores.

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

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.

1. Faça login no seu Logto Console.

2. Vá em Aplicativos → Criar aplicativo → Aplicativo de terceiros -> OIDC.

3. Preencha o nome do aplicativo e outros campos obrigatórios, depois clique em Criar aplicativo.

4. Clique na guia Permissões, na seção Usuário, clique em "Adicionar".

5. Na janela aberta -> Dados do usuário -> selecione as permissões profile, email, depois clique em Salvar.

6. No aplicativo de terceiros, configure os escopos para solicitar as permissões (escopos) openid profile email.

   Observação: openid é obrigatório para OIDC, e profile e email são as permissões que você adicionou na etapa anterior.

7. Configure o redirect URI do seu aplicativo de terceiros conforme necessário. Lembre-se de atualizar o redirect URI também no Logto.

---

Por baixo dos panos, um aplicativo de terceiros é apenas 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.

Se você não está familiarizado com OAuth 2.0 ou OIDC, pode começar seguindo um dos nossos guias rápidos de “Web tradicional”.

Alguns pontos para ter em mente:

1. O Logto atualmente exige que aplicativos de terceiros sejam aplicativos “Web tradicional”. Em outras palavras, o aplicativo precisa de um servidor backend (ou backend-for-frontend) para armazenar o client secret com segurança.
2. A maioria dos nossos guias rápidos são escritos para aplicativos de primeira parte, mas você ainda pode usá-los como referência para integração de aplicativos de terceiros.
3. 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.

Você pode encontrar mais informações em nossos guias rápidos.

Configurar o servidor MCP

Criar projeto e instalar dependências

Python

mkdir mcp-server
cd mcp-server
uv init # Ou use sua própria estrutura de projeto
uv add "mcp[cli]" starlette uvicorn mcpauth # Ou use qualquer gerenciador de pacotes de sua preferência

Node.js

mkdir mcp-server
cd mcp-server
npm init -y
npm install @modelcontextprotocol/sdk express mcp-auth # Ou use qualquer gerenciador de pacotes de sua preferência

Configurar autenticação MCP com Logto

Lembre-se de substituir <your-logto-issuer-endpoint> pelo endpoint do emissor que você copiou anteriormente.

Python

Em whoami.py:

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

auth_issuer = '<your-logto-issuer-endpoint>'
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

Node.js

Em whoami.js:

import { MCPAuth, fetchServerConfig } from 'mcp-auth';

const authIssuer = '<your-logto-issuer-endpoint>';
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig(authIssuer, { type: 'oidc' }),
});

Implementar verificação de token

Como vamos verificar o token de acesso (Access token) e recuperar as informações do usuário, precisamos implementar a verificação do token de acesso conforme abaixo:

Python

import requests
from mcpauth.types import AuthInfo

def verify_access_token(token: str) -> AuthInfo:
    endpoint = auth_server_config.metadata.userinfo_endpoint
    response = requests.get(
        endpoint,
        headers={"Authorization": f"Bearer {token}"},
    )
    response.raise_for_status()
    data = response.json()
    return AuthInfo(
        token=token,
        subject=data.get("sub"),
        issuer=auth_server_config.metadata.issuer,
        claims=data,
    )

Node.js

const verifyToken = async (token) => {
  const { userinfoEndpoint, issuer } = mcpAuth.config.server.metadata;
  const response = await fetch(userinfoEndpoint, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!response.ok) throw new Error('Token verification failed');
  const userInfo = await response.json();
  return {
    token,
    issuer,
    subject: userInfo.sub,
    claims: userInfo,
  };
};

Implementar a ferramenta "whoami"

Agora, vamos implementar a ferramenta "whoami" que retorna as reivindicações de identidade do usuário atual, solicitando o endpoint userinfo com o token de acesso enviado pelo cliente.

nota:

Estamos usando o transporte SSE para o exemplo devido à falta de suporte oficial ao transporte HTTP Streamable na versão atual do SDK. Teoricamente, você pode usar qualquer transporte compatível com HTTP.

Python

from mcp.server.fastmcp import FastMCP
from starlette.applications import Starlette
from starlette.routing import Mount
from starlette.middleware import Middleware

mcp = FastMCP("WhoAmI")

@mcp.tool()
def whoami() -> dict:
    """
    Retorna as informações de identidade do usuário atual.
    """
    return (
        mcp_auth.auth_info.claims
        if mcp_auth.auth_info
        else {"error": "Not authenticated"}
    )

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token))
app = Starlette(
    routes=[
        mcp_auth.metadata_route(),  # Serve metadados OIDC para descoberta
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

Execute o servidor com:

uvicorn whoami:app --host 0.0.0.0 --port 3001

Node.js

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import express from 'express';

// Crie o servidor MCP e registre a ferramenta whoami
const server = new McpServer({ name: 'WhoAmI', version: '0.0.0' });
server.tool('whoami', ({ authInfo }) => ({
  content: [
    { type: 'text', text: JSON.stringify(authInfo?.claims ?? { error: 'Not authenticated' }) },
  ],
}));

// App Express & middleware MCP Auth
const app = express();
app.use(mcpAuth.delegatedRouter());
app.use(mcpAuth.bearerAuth(verifyToken));

// Transporte SSE (como na documentação do SDK)
const transports = {};
app.get('/sse', async (_req, res) => {
  const transport = new SSEServerTransport('/messages', res);
  transports[transport.sessionId] = transport;
  res.on('close', () => delete transports[transport.sessionId]);
  await server.connect(transport);
});
app.post('/messages', async (req, res) => {
  const sessionId = String(req.query.sessionId);
  const transport = transports[sessionId];
  if (transport) await transport.handlePostMessage(req, res, req.body);
  else res.status(400).send('No transport found for sessionId');
});

app.listen(3001);

Execute o servidor com:

node whoami.js

Testar a integração

1. Inicie o servidor MCP.
2. Inicie o agente de IA.
3. No cliente, invoque a ferramenta whoami para recuperar as reivindicações de identidade do usuário atual.
4. O cliente deve lidar com a resposta 401 Não autorizado e redirecionar o usuário para o Logto para autenticação.
5. Após a autenticação bem-sucedida, o cliente deve receber um token de acesso e usá-lo para fazer requisições ao servidor MCP.
6. O cliente deve ser capaz de recuperar as reivindicações de identidade do servidor MCP usando o token de acesso.

Python

O código completo do servidor MCP pode ser encontrado no repositório mcp-auth/python.

Node.js

O código completo do servidor MCP pode ser encontrado no repositório mcp-auth/js.