Pular para o conteúdo principal

Primeiros passos

Escolha um provedor compatível com OAuth 2.1 ou OpenID Connect​

A especificação MCP possui alguns requisitos específicos para autorização:

Embora os dois últimos não sejam obrigatórios, o primeiro é necessário para garantir uma implementação segura e compatível.

nota

No novo draft do MCP, o RFC 8414 será obrigatório para servidores de autorização (provedores). Atualizaremos a documentação assim que o novo draft for finalizado.

Você pode conferir a lista de provedores compatíveis com MCP para ver se seu provedor é suportado.

Instale o MCP Auth SDK​

O MCP Auth está disponível para Python e TypeScript. Nos avise se precisar de suporte para outra linguagem ou framework!

pip install mcpauth

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

Inicialize o MCP Auth​

O primeiro passo é inicializar a instância do MCP Auth com os metadados do servidor de autorização do seu provedor. Se seu provedor estiver em conformidade com um dos seguintes:

Você pode usar a função integrada para buscar os metadados e inicializar a instância do MCP Auth:

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

mcp_auth = MCPAuth(
    server=fetch_server_config(
      '<auth-server-url>',
      type=AuthServerType.OIDC # ou AuthServerType.OAUTH
    )
)

Se você precisar especificar manualmente a URL dos metadados ou endpoints, confira Outras formas de inicializar o MCP Auth.

Monte o endpoint de metadados​

Para estar em conformidade com a especificação MCP atual, o MCP Auth monta o endpoint OAuth 2.0 Authorization Server Metadata (/.well-known/oauth-authorization-server) no seu servidor MCP:

from starlette.applications import Starlette

app = Starlette(routes=[
    mcp_auth.metadata_route(),
])

As URLs nos metadados são mantidas como estão, então o papel de servidor de autorização é totalmente delegado ao provedor. Você pode testar o endpoint de metadados acessando /.well-known/oauth-authorization-server no seu servidor MCP.

Por que apenas o endpoint de metadados?​

Você pode notar que os SDKs oficiais fornecem um roteador de autenticação que monta endpoints de autorização como /authorize, /token, etc. Veja por que não fazemos isso:

  1. Montar apenas o endpoint de metadados permite que você aproveite todas as capacidades do seu provedor sem "reinventar a roda" e injetar complexidade desnecessária no seu servidor MCP.
  2. Também há um esforço em andamento para transferir o papel do servidor MCP para um resource server e exigir OAuth 2.0 Protected Resource Metadata (RFC 9728). Isso significa que o servidor MCP não lidará mais com nenhuma lógica de autorização (incluindo o endpoint de metadados), servindo apenas como um resource server que depende do provedor para autenticação e autorização.
nota

Atualizaremos o MCP Auth para suportar a nova especificação MCP quando ela for finalizada. Enquanto isso, você pode usar a versão atual, que é compatível com a especificação vigente.

Use o middleware Bearer auth​

Depois de inicializar a instância do MCP Auth, você pode aplicar o middleware Bearer auth para proteger suas rotas MCP:

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

mcp = FastMCP()
mcp_auth = MCPAuth(
  # Inicialize com a configuração do seu servidor de autenticação
)
bearer_auth = mcp_auth.bearer_auth_middleware(
    "jwt", required_scopes=["read", "write"]
)

app = Starlette(routes=[
    mcp_auth.metadata_route(),
    Mount(
        "/",
        app=mcp.sse_app(),
        middleware=[Middleware(bearer_auth)],
    ),
])

No exemplo acima, especificamos o tipo de token jwt e exigimos os escopos read e write. Ele validará automaticamente o JWT (JSON Web Token) e preencherá um objeto com as informações do usuário autenticado.

info

Nunca ouviu falar de JWT (JSON Web Token)? Não se preocupe, continue lendo a documentação e explicaremos quando necessário. Você também pode conferir o Auth Wiki para uma introdução rápida.

Para mais informações sobre a configuração do Bearer auth, confira Configurar Bearer auth.

Recupere as informações de autenticação na sua implementação MCP​

Depois que o middleware Bearer auth for aplicado, você pode acessar as informações do usuário autenticado (ou identidade) na sua implementação MCP:

O MCP Auth armazenará as informações do usuário autenticado em uma variável de contexto após a autenticação bem-sucedida, uma vez que o middleware Bearer auth for aplicado. Você pode acessá-la em seus handlers de ferramentas MCP assim:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP()
mcp_auth = MCPAuth(
  # Inicialize com a configuração do seu servidor de autenticação
)

@mcp.tool()
def add(a: int, b: int):
    """
    Uma ferramenta que soma dois números.
    As informações do usuário autenticado estarão disponíveis no contexto.
    """
    auth_info = mcp_auth.auth_info # Acesse as informações de autenticação no contexto atual
    if auth_info:
        print(f"Usuário autenticado: {auth_info.claims}")
    return a + b

Próximos passos​

Continue lendo para aprender um exemplo de ponta a ponta de como integrar o MCP Auth ao seu servidor MCP e como lidar com o fluxo de autenticação em clientes MCP.