Pular para o conteúdo principal

Tutorial: Quem sou eu? (Who am I?)

Este tutorial irá guiá-lo pelo processo de configuração do MCP Auth para autenticar usuários e recuperar suas informações de identidade do servidor de autorização.

Após concluir este tutorial, você terá:

  • ✅ Uma compreensão básica de como usar o MCP Auth para autenticar usuários.
  • ✅ Um servidor MCP que oferece uma ferramenta para recuperar informações de identidade do usuário.

Visão geral (Overview)​

O tutorial envolverá os seguintes componentes:

  • Servidor MCP (MCP server): Um servidor MCP simples que utiliza os SDKs oficiais do MCP para lidar com requisições.
  • MCP inspector: Uma ferramenta visual de testes para servidores MCP. Também atua como um cliente OAuth / OIDC para iniciar o fluxo de autorização e recuperar tokens de acesso.
  • Servidor de autorização (Authorization server): Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários e emite tokens de acesso.

Aqui está um diagrama de alto nível da interação entre esses componentes:

Entenda seu servidor de autorização (Understand your authorization server)​

Recuperando informações de identidade do usuário (Retrieving user identity information)​

Para concluir este tutorial, seu servidor de autorização deve oferecer uma API para recuperar informações de identidade do usuário:

Logto é um provedor OpenID Connect que suporta o endpoint padrão userinfo para recuperar informações de identidade do usuário.

Para buscar um token de acesso que possa ser usado para acessar o endpoint userinfo, pelo menos dois escopos são necessários: openid e profile. Você pode continuar lendo, pois abordaremos a configuração de escopos mais adiante.

Registro dinâmico de cliente (Dynamic Client Registration)​

O registro dinâmico de cliente não é necessário para este tutorial, mas pode ser útil se você quiser automatizar o processo de registro do cliente MCP com seu servidor de autorização. Consulte O registro dinâmico de cliente é necessário? para mais detalhes.

Configure o servidor MCP (Set up the MCP server)​

Usaremos os SDKs oficiais do MCP para criar um servidor MCP com uma ferramenta whoami que recupera informações de identidade do usuário do servidor de autorização.

Crie um novo projeto (Create a new project)​

mkdir mcp-server
cd mcp-server
uv init # Ou use `pipenv` ou `poetry` para criar um novo ambiente virtual

Instale o MCP SDK e dependências (Install the MCP SDK and dependencies)​

pip install "mcp[cli]" starlette uvicorn

Ou qualquer outro gerenciador de pacotes de sua preferência, como uv ou poetry.

Crie o servidor MCP (Create the MCP server)​

Primeiro, vamos criar um servidor MCP que implementa uma ferramenta whoami.

Crie um arquivo chamado whoami.py e adicione o seguinte código:

from mcp.server.fastmcp import FastMCP
from starlette.applications import Starlette
from starlette.routing import Mount
from typing import Any

mcp = FastMCP("WhoAmI")

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Uma ferramenta que retorna as informações do usuário atual."""
    return {"error": "Not authenticated"}

app = Starlette(
    routes=[Mount('/', app=mcp.sse_app())]
)

Execute o servidor com:

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

Inspecione o servidor MCP (Inspect the MCP server)​

Clone e execute o MCP inspector (Clone and run MCP inspector)​

Agora que temos o servidor MCP em execução, podemos usar o MCP inspector para ver se a ferramenta whoami está disponível.

Devido à limitação da implementação atual, fizemos um fork do MCP inspector para torná-lo mais flexível e escalável para autenticação e autorização. Também enviamos um pull request para o repositório original para incluir nossas alterações.

Para executar o MCP inspector, você pode usar o seguinte comando (Node.js é necessário):

git clone https://github.com/mcp-auth/inspector.git
cd inspector
npm install
npm run dev

Em seguida, abra seu navegador e acesse http://localhost:6274/ (ou outro URL exibido no terminal) para acessar o MCP inspector.

Conecte o MCP inspector ao servidor MCP (Connect MCP inspector to the MCP server)​

Antes de prosseguir, verifique a seguinte configuração no MCP inspector:

  • Tipo de transporte (Transport Type): Defina como SSE.
  • URL: Defina como a URL do seu servidor MCP. No nosso caso, deve ser http://localhost:3001/sse.

Agora você pode clicar no botão "Connect" para ver se o MCP inspector consegue se conectar ao servidor MCP. Se tudo estiver correto, você verá o status "Connected" no MCP inspector.

Ponto de verificação: Execute a ferramenta whoami (Checkpoint: Run the whoami tool)​

  1. No menu superior do MCP inspector, clique na guia "Tools".
  2. Clique no botão "List Tools".
  3. Você deve ver a ferramenta whoami listada na página. Clique nela para abrir os detalhes da ferramenta.
  4. Você deve ver o botão "Run Tool" no lado direito. Clique nele para executar a ferramenta.
  5. Você deve ver o resultado da ferramenta com a resposta JSON {"error": "Not authenticated"}.

Primeira execução do MCP inspector

Integre com seu servidor de autorização (Integrate with your authorization server)​

Para concluir esta seção, há várias considerações a serem levadas em conta:

A URL do emissor do seu servidor de autorização (The issuer URL of your authorization server)

Normalmente, é a URL base do seu servidor de autorização, como https://auth.example.com. Alguns provedores podem ter um caminho como https://example.logto.app/oidc, então certifique-se de verificar a documentação do seu provedor.

Como recuperar os metadados do servidor de autorização (How to retrieve the authorization server metadata)
  • Se seu servidor de autorização estiver em conformidade com o OAuth 2.0 Authorization Server Metadata ou OpenID Connect Discovery, você pode usar as utilidades integradas do MCP Auth para buscar os metadados automaticamente.
  • Se seu servidor de autorização não estiver em conformidade com esses padrões, você precisará especificar manualmente a URL dos metadados ou endpoints na configuração do servidor MCP. Verifique a documentação do seu provedor para os endpoints específicos.
Como registrar o MCP inspector como cliente em seu servidor de autorização (How to register the MCP inspector as a client in your authorization server)
  • Se seu servidor de autorização suporta Dynamic Client Registration, você pode pular esta etapa, pois o MCP inspector se registrará automaticamente como cliente.
  • Se seu servidor de autorização não suporta Dynamic Client Registration, você precisará registrar manualmente o MCP inspector como cliente em seu servidor de autorização.
Como recuperar informações de identidade do usuário e como configurar os parâmetros da solicitação de autorização (How to retrieve user identity information and how to configure the authorization request parameters)

  • Para provedores OpenID Connect: normalmente você precisa solicitar pelo menos os escopos openid e profile ao iniciar o fluxo de autorização. Isso garantirá que o token de acesso retornado pelo servidor de autorização contenha os escopos necessários para acessar o endpoint userinfo para recuperar informações de identidade do usuário.

    Nota: Alguns provedores podem não suportar o endpoint userinfo.

  • Para provedores OAuth 2.0 / OAuth 2.1: verifique a documentação do seu provedor para saber como recuperar informações de identidade do usuário usando um token de acesso e quais parâmetros são necessários para obter esse token ao invocar o fluxo de autorização.

Embora cada provedor possa ter seus próprios requisitos específicos, as etapas a seguir irão guiá-lo pelo processo de integração do MCP inspector e do servidor MCP com configurações específicas do provedor.

Registre o MCP inspector como cliente (Register MCP inspector as a client)​

Integrar com o Logto é simples, pois é um provedor OpenID Connect que suporta o endpoint padrão userinfo para recuperar informações de identidade do usuário.

Como o Logto ainda não suporta Dynamic Client Registration, você precisará registrar manualmente o MCP inspector como cliente em seu tenant Logto:

  1. Abra seu MCP inspector, clique no botão "OAuth Configuration". Copie o valor Redirect URL (auto-populated), que deve ser algo como http://localhost:6274/oauth/callback.
  2. Faça login no Logto Console (ou seu Logto Console auto-hospedado).
  3. Navegue até a aba "Applications", clique em "Create application". No final da página, clique em "Create app without framework".
  4. Preencha os detalhes do aplicativo e clique em "Create application":
    • Selecione um tipo de aplicativo: Escolha "Single-page application".
    • Nome do aplicativo: Insira um nome para seu aplicativo, por exemplo, "MCP Inspector".
  5. Na seção "Settings / Redirect URIs", cole o valor Redirect URL (auto-populated) que você copiou do MCP inspector. Em seguida, clique em "Save changes" na barra inferior.
  6. No cartão superior, você verá o valor "App ID". Copie-o.
  7. Volte ao MCP inspector e cole o valor "App ID" na seção "OAuth Configuration" em "Client ID".
  8. Insira o valor {"scope": "openid profile email"} no campo "Auth Params". Isso garantirá que o token de acesso retornado pelo Logto contenha os escopos necessários para acessar o endpoint userinfo.

Configure o MCP auth (Set up MCP auth)​

No seu projeto do servidor MCP, você precisa instalar o SDK MCP Auth e configurá-lo para usar os metadados do seu servidor de autorização.

Primeiro, instale o pacote mcpauth:

pip install mcpauth

Ou qualquer outro gerenciador de pacotes de sua preferência, como uv ou poetry.

O MCP Auth requer os metadados do servidor de autorização para poder inicializar. Dependendo do seu provedor:

A URL do emissor pode ser encontrada na página de detalhes do seu aplicativo no Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como https://my-project.logto.app/oidc.

Atualize o whoami.py para incluir a configuração do MCP Auth:

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

auth_issuer = '<issuer-endpoint>'  # Substitua pelo endpoint do seu emissor
auth_server_config = fetch_server_config(auth_issuer, type=AuthServerType.OIDC)
mcp_auth = MCPAuth(server=auth_server_config)

Agora, precisamos criar um verificador personalizado de token de acesso (Access token) que buscará as informações de identidade do usuário no servidor de autorização usando o token de acesso fornecido pelo inspetor MCP.

import pydantic
import requests
from mcpauth.exceptions import (
    MCPAuthTokenVerificationException,
    MCPAuthTokenVerificationExceptionCode,
)
from mcpauth.types import AuthInfo

def verify_access_token(token: str) -> AuthInfo:
    """
    Verifica o Bearer token fornecido buscando informações do usuário no servidor de autorização.
    Se o token for válido, retorna um objeto `AuthInfo` contendo as informações do usuário.

    :param token: O Bearer token recebido do inspetor MCP.
    """

    issuer = auth_server_config.metadata.issuer
    endpoint = auth_server_config.metadata.userinfo_endpoint # O provedor deve suportar o endpoint userinfo
    if not endpoint:
        raise ValueError(
            "O endpoint userinfo não está configurado nos metadados do servidor de autenticação."
        )

    try:
        response = requests.get(
            endpoint,
            headers={"Authorization": f"Bearer {token}"}, # Cabeçalho padrão Bearer token
        )
        response.raise_for_status() # Garante que um erro seja lançado para erros HTTP
        json = response.json() # Analisa a resposta JSON
        return AuthInfo(
            token=token,
            subject=json.get("sub"), # 'sub' é uma reivindicação padrão para o sujeito (ID do usuário)
            issuer=issuer, # Usa o emissor dos metadados
            claims=json, # Inclui todas as reivindicações (campos JSON) retornadas pelo endpoint userinfo
        )
    # `AuthInfo` é um modelo Pydantic, então erros de validação geralmente significam que a resposta não correspondeu
    # à estrutura esperada
    except pydantic.ValidationError as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.INVALID_TOKEN,
            cause=e,
        )
    # Lida com outras exceções que podem ocorrer durante a requisição
    except Exception as e:
        raise MCPAuthTokenVerificationException(
            MCPAuthTokenVerificationExceptionCode.TOKEN_VERIFICATION_FAILED,
            cause=e,
        )

Atualize o servidor MCP (Update MCP server)​

Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e o middleware do MCP Auth, e então fazer a ferramenta whoami retornar as informações reais de identidade do usuário.

@mcp.tool()
def whoami() -> dict[str, Any]:
    """Uma ferramenta que retorna as informações do usuário atual."""
    return (
        mcp_auth.auth_info.claims
        if mcp_auth.auth_info # Isso será preenchido pelo middleware Bearer auth
        else {"error": "Not authenticated"}
    )

# ...

bearer_auth = Middleware(mcp_auth.bearer_auth_middleware(verify_access_token))
app = Starlette(
    routes=[
        # Adicione a rota de metadados (`/.well-known/oauth-authorization-server`)
        mcp_auth.metadata_route(),
        # Proteja o servidor MCP com o middleware Bearer auth
        Mount('/', app=mcp.sse_app(), middleware=[bearer_auth]),
    ],
)

Ponto de verificação: Execute a ferramenta whoami com autenticação (Checkpoint: Run the whoami tool with authentication)​

Reinicie seu servidor MCP e abra o MCP inspector no navegador. Ao clicar no botão "Connect", você deve ser redirecionado para a página de login do seu servidor de autorização.

Depois de fazer login e retornar ao MCP inspector, repita as ações que fizemos no ponto de verificação anterior para executar a ferramenta whoami. Desta vez, você deve ver as informações de identidade do usuário retornadas pelo servidor de autorização.

Resultado da ferramenta whoami no MCP inspector

info

Confira o repositório do MCP Auth Python SDK para o código completo do servidor MCP (versão OIDC).

Notas finais (Closing notes)​

🎊 Parabéns! Você concluiu com sucesso o tutorial. Vamos recapitular o que fizemos:

  • Configuração de um servidor MCP básico com a ferramenta whoami
  • Integração do servidor MCP com um servidor de autorização usando MCP Auth
  • Configuração do MCP Inspector para autenticar usuários e recuperar suas informações de identidade

Você também pode explorar alguns tópicos avançados, incluindo:

Não deixe de conferir outros tutoriais e a documentação para aproveitar ao máximo o MCP Auth.