Pular para o conteúdo principal

Tutorial: Construa um gerenciador de tarefas

SDK Python disponível

MCP Auth também está disponível para Python! Confira o repositório do SDK Python para instalação e uso.

Neste tutorial, vamos construir um servidor MCP de gerenciador de tarefas com Autenticação (Authentication) e Autorização (Authorization) de usuários. Seguindo a especificação mais recente do MCP, nosso servidor MCP atuará como um Servidor de Recursos (Resource Server) OAuth 2.0 que valida tokens de acesso e aplica permissões baseadas em escopo.

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

  • ✅ Uma compreensão básica de como configurar Controle de acesso baseado em papel (RBAC) no seu servidor MCP.
  • ✅ Um servidor MCP que atua como um Servidor de Recursos, consumindo tokens de acesso emitidos por um Servidor de Autorização.
  • ✅ Uma implementação funcional de aplicação de permissões baseadas em escopo para operações de tarefas.

Visão geral​

O tutorial envolverá os seguintes componentes:

  • Cliente MCP (MCP Inspector): Uma ferramenta visual de testes para servidores MCP que atua como um cliente OAuth 2.0/OIDC. Ele inicia o fluxo de autorização com o servidor de autorização e obtém tokens de acesso para autenticar solicitações ao servidor MCP.
  • Servidor de Autorização: Um provedor OAuth 2.1 ou OpenID Connect que gerencia identidades de usuários, autentica usuários e emite tokens de acesso com os escopos apropriados para clientes autorizados.
  • Servidor MCP (Servidor de Recursos): De acordo com a especificação mais recente do MCP, o servidor MCP atua como um Servidor de Recursos no framework OAuth 2.0. Ele valida tokens de acesso emitidos pelo servidor de autorização e aplica permissões baseadas em escopo para operações de tarefas.

Esta arquitetura segue o fluxo padrão do OAuth 2.0 onde:

  • O MCP Inspector solicita recursos protegidos em nome do usuário
  • O Servidor de Autorização autentica o usuário e emite tokens de acesso
  • O Servidor MCP valida tokens e serve recursos protegidos com base nas permissões concedidas

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

Entenda seu servidor de autorização​

Tokens de acesso com escopos​

Para implementar Controle de acesso baseado em papel (RBAC) no seu servidor MCP, seu servidor de autorização precisa suportar a emissão de tokens de acesso com escopos. Escopos representam as permissões que um usuário recebeu.

Logto oferece suporte a RBAC por meio de seus Recursos de API (API resources) (conforme RFC 8707: Resource Indicators for OAuth 2.0) e recursos de papéis. Veja como configurar:

  1. Faça login no Logto Console (ou no seu Logto Console auto-hospedado)

  2. Crie recurso de API e escopos:

    • Vá em "Recursos de API"
    • Crie um novo recurso de API chamado "Todo Manager"
    • Adicione os seguintes escopos:
      • create:todos: "Criar novas tarefas"
      • read:todos: "Ler todas as tarefas"
      • delete:todos: "Excluir qualquer tarefa"

  3. Crie papéis (recomendado para facilitar o gerenciamento):

    • Vá em "Papéis"
    • Crie um papel "Admin" e atribua todos os escopos (create:todos, read:todos, delete:todos)
    • Crie um papel "User" e atribua apenas o escopo create:todos

  4. Atribua permissões:

    • Vá em "Usuários"
    • Selecione um usuário
    • Você pode:
      • Atribuir papéis na aba "Papéis" (recomendado)
      • Ou atribuir escopos diretamente na aba "Permissões"

Os escopos serão incluídos na reivindicação scope do token de acesso JWT como uma string separada por espaços.

Validando tokens e verificando permissões​

De acordo com a especificação mais recente do MCP, o servidor MCP atua como um Servidor de Recursos (Resource Server) no framework OAuth 2.0. Como Servidor de Recursos, o servidor MCP tem as seguintes responsabilidades:

  1. Validação de Token: Verificar a autenticidade e integridade dos tokens de acesso recebidos dos clientes MCP
  2. Aplicação de Escopo: Extrair e validar os escopos do token de acesso para determinar quais operações o cliente está autorizado a executar
  3. Proteção de Recursos: Servir apenas recursos protegidos (executar ferramentas) quando o cliente apresentar tokens válidos com permissões suficientes

Quando seu servidor MCP recebe uma solicitação, ele executa o seguinte processo de validação:

  1. Extrai o token de acesso do cabeçalho Authorization (formato Bearer token)
  2. Valida a assinatura e expiração do token de acesso
  3. Extrai os escopos e informações do usuário do token validado
  4. Verifica se o token possui os escopos necessários para a operação solicitada

Por exemplo, se um usuário quiser criar uma nova tarefa, seu token de acesso deve incluir o escopo create:todos. Veja como funciona o fluxo de validação do Servidor de Recursos:

Registro dinâmico de cliente​

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. Veja O Registro Dinâmico de Cliente é necessário? para mais detalhes.

Entenda o RBAC no gerenciador de tarefas​

Para fins de demonstração, implementaremos um sistema simples de Controle de acesso baseado em papel (RBAC) em nosso servidor MCP de gerenciador de tarefas. Isso mostrará os princípios básicos do RBAC mantendo a implementação direta.

nota

Embora este tutorial demonstre o gerenciamento de escopos baseado em RBAC, é importante observar que nem todos os provedores de autenticação implementam o gerenciamento de escopos por meio de papéis. Alguns provedores podem ter suas próprias implementações e mecanismos exclusivos para gerenciar controle de acesso e permissões.

Ferramentas e escopos​

Nosso servidor MCP de gerenciador de tarefas fornece três ferramentas principais:

  • create-todo: Criar uma nova tarefa
  • get-todos: Listar todas as tarefas
  • delete-todo: Excluir uma tarefa pelo ID

Para controlar o acesso a essas ferramentas, definimos os seguintes escopos:

  • create:todos: Permite criar novas tarefas
  • delete:todos: Permite excluir tarefas existentes
  • read:todos: Permite consultar e recuperar a lista de todas as tarefas

Papéis e permissões​

Definiremos dois papéis com diferentes níveis de acesso:

Papelcreate:todosread:todosdelete:todos
Admin✅✅✅
User✅
  • User: Um usuário comum que pode criar tarefas e visualizar ou excluir apenas suas próprias tarefas
  • Admin: Um administrador que pode criar, visualizar e excluir todas as tarefas, independentemente da propriedade

Propriedade do recurso​

Embora a tabela de permissões acima mostre os escopos explícitos atribuídos a cada papel, há um princípio importante de propriedade de recurso a considerar:

  • Usuários não possuem os escopos read:todos ou delete:todos, mas ainda podem:
    • Ler suas próprias tarefas
    • Excluir suas próprias tarefas
  • Admins possuem permissões totais (read:todos e delete:todos), permitindo que eles:
    • Visualizem todas as tarefas do sistema
    • Excluam qualquer tarefa, independentemente da propriedade

Isso demonstra um padrão comum em sistemas RBAC onde a propriedade do recurso concede permissões implícitas aos usuários para seus próprios recursos, enquanto papéis administrativos recebem permissões explícitas para todos os recursos.

Saiba mais

Para se aprofundar nos conceitos e melhores práticas de RBAC, confira Dominando RBAC: Um exemplo real e abrangente.

Configure a autorização no seu provedor​

Para implementar o sistema de controle de acesso que descrevemos anteriormente, você precisará configurar seu servidor de autorização para suportar os escopos necessários. Veja como fazer isso com diferentes provedores:

Logto oferece suporte a RBAC por meio de seus Recursos de API (API resources) e recursos de papéis. Veja como configurar:

  1. Faça login no Logto Console (ou no seu Logto Console auto-hospedado)

  2. Crie recurso de API e escopos:

    • Vá em "Recursos de API"
    • Crie um novo recurso de API chamado "Todo Manager" usando http://localhost:3001 como indicador de recurso.
      • Importante: O indicador de recurso deve corresponder à URL do seu servidor MCP. Para este tutorial, usamos http://localhost:3001 pois nosso servidor MCP roda na porta 3001. Em produção, use a URL real do seu servidor MCP (ex: https://seu-servidor-mcp.exemplo.com).
    • Crie os seguintes escopos:
      • create:todos: "Criar novas tarefas"
      • read:todos: "Ler todas as tarefas"
      • delete:todos: "Excluir qualquer tarefa"

  3. Crie papéis (recomendado para facilitar o gerenciamento):

    • Vá em "Papéis"
    • Crie um papel "Admin" e atribua todos os escopos (create:todos, read:todos, delete:todos)
    • Crie um papel "User" e atribua apenas o escopo create:todos
    • Na página de detalhes do papel "User", vá para a aba "Geral" e defina o papel "User" como o "Papel padrão".

  4. Gerencie papéis e permissões dos usuários:

    • Para novos usuários:
      • Eles receberão automaticamente o papel "User" já que o definimos como padrão
    • Para usuários existentes:
      • Vá em "Gerenciamento de usuários"
      • Selecione um usuário
      • Atribua papéis para o usuário na aba "Papéis"
Gerenciamento programático de papéis

Você também pode usar a Management API do Logto para gerenciar papéis de usuários programaticamente. Isso é especialmente útil para automação ou ao construir painéis administrativos.

Ao solicitar um token de acesso, o Logto incluirá os escopos na reivindicação scope do token com base nas permissões do papel do usuário.

Após configurar seu servidor de autorização, os usuários receberão tokens de acesso contendo seus escopos concedidos. O servidor MCP usará esses escopos para determinar:

  • Se um usuário pode criar novas tarefas (create:todos)
  • Se um usuário pode visualizar todas as tarefas (read:todos) ou apenas as suas
  • Se um usuário pode excluir qualquer tarefa (delete:todos) ou apenas as suas

Configure o servidor MCP​

Usaremos os SDKs oficiais do MCP para criar nosso servidor MCP de gerenciador de tarefas.

Crie um novo projeto​

Configure um novo projeto Node.js:

mkdir mcp-server
cd mcp-server
npm init -y # Ou use `pnpm init`
npm pkg set type="module"
npm pkg set main="todo-manager.ts"
npm pkg set scripts.start="node --experimental-strip-types todo-manager.ts"
nota

Estamos usando TypeScript em nossos exemplos pois o Node.js v22.6.0+ suporta rodar TypeScript nativamente usando a flag --experimental-strip-types. Se você estiver usando JavaScript, o código será semelhante - apenas certifique-se de estar usando Node.js v22.6.0 ou superior. Veja a documentação do Node.js para detalhes.

Instale o SDK MCP e dependências​

npm install @modelcontextprotocol/sdk express zod

Ou qualquer outro gerenciador de pacotes de sua preferência, como pnpm ou yarn.

Crie o servidor MCP​

Crie um arquivo chamado todo-manager.ts e adicione o seguinte código:

// todo-manager.ts

import { z } from 'zod';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import express, { type Request, type Response } from 'express';

// Crie um servidor MCP
const server = new McpServer({
  name: 'Todo Manager',
  version: '0.0.0',
});

server.registerTool(
  'create-todo',
  {
    description: 'Criar uma nova tarefa',
    inputSchema: { content: z.string() },
  },
  async ({ content }) => {
    return {
      content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }],
    };
  }
);

server.registerTool(
  'get-todos',
  {
    description: 'Listar todas as tarefas',
    inputSchema: {},
  },
  async () => {
    return {
      content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }],
    };
  }
);

server.registerTool(
  'delete-todo',
  {
    description: 'Excluir uma tarefa pelo id',
    inputSchema: { id: z.string() },
  },
  async ({ id }) => {
    return {
      content: [{ type: 'text', text: JSON.stringify({ error: 'Not implemented' }) }],
    };
  }
);

// Abaixo está o código boilerplate da documentação do SDK MCP
const PORT = 3001;
const app = express();

app.post('/', async (request: Request, response: Response) => {
  // No modo stateless, crie uma nova instância de transporte e servidor para cada requisição
  // para garantir isolamento completo. Uma única instância causaria colisão de IDs de requisição
  // quando múltiplos clientes conectam simultaneamente.

  try {
    const transport: StreamableHTTPServerTransport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined,
    });
    response.on('close', async () => {
      console.log('Request closed');
      await transport.close();
      await server.close();
    });
    await server.connect(transport);
    await transport.handleRequest(request, response, request.body);
  } catch (error) {
    console.error('Erro ao lidar com a solicitação MCP:', error);
    if (!response.headersSent) {
      response.status(500).json({
        jsonrpc: '2.0',
        error: {
          code: -32_603,
          message: 'Erro interno do servidor',
        },
        id: null,
      });
    }
  }
});

// Notificações SSE não suportadas no modo stateless
app.get('/', async (request: Request, response: Response) => {
  console.log('Recebida solicitação GET MCP');
  response.writeHead(405).end(
    JSON.stringify({
      jsonrpc: '2.0',
      error: {
        code: -32_000,
        message: 'Método não permitido.',
      },
      id: null,
    })
  );
});

// Encerramento de sessão não é necessário no modo stateless
app.delete('/', async (request: Request, response: Response) => {
  console.log('Recebida solicitação DELETE MCP');
  response.writeHead(405).end(
    JSON.stringify({
      jsonrpc: '2.0',
      error: {
        code: -32_000,
        message: 'Método não permitido.',
      },
      id: null,
    })
  );
});

app.listen(PORT);

Execute o servidor com:

npm start

Inspecione o servidor MCP​

Clone e execute o MCP inspector​

Agora que temos o servidor MCP rodando, podemos usar o MCP inspector para ver se as ferramentas estão disponíveis.

O MCP inspector oficial v0.16.2 possui alguns bugs que afetam a funcionalidade de autenticação. Para resolver esses problemas, criamos uma versão corrigida do MCP inspector que inclui as correções necessárias para os fluxos de autenticação OAuth/OIDC. Também enviamos pull requests para o repositório oficial para contribuir com essas correções.

Para rodar o MCP inspector, use o seguinte comando (Node.js é necessário):

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

O MCP inspector abrirá automaticamente em seu navegador padrão, ou você pode acessá-lo manualmente clicando no link exibido no terminal (certifique-se de clicar no link que inclui o parâmetro MCP_PROXY_AUTH_TOKEN, como http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=458ae4a4...acab1907).

Conecte o MCP inspector ao servidor MCP​

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

  • Tipo de transporte: Defina como Streamable HTTP.
  • URL: Defina para a URL do seu servidor MCP. No nosso caso, deve ser http://localhost:3001.

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

Checkpoint: Execute as ferramentas do gerenciador de tarefas​

  1. No menu superior do MCP inspector, clique na aba "Tools".
  2. Clique no botão "List Tools".
  3. Você deve ver as ferramentas create-todo, get-todos e delete-todo listadas na página. Clique para abrir os detalhes da ferramenta.
  4. Você verá o botão "Run Tool" no lado direito. Clique nele e insira os parâmetros necessários para executar a ferramenta.
  5. Você verá o resultado da ferramenta com a resposta JSON {"error": "Not implemented"}.

Primeira execução do MCP inspector

Integre com seu servidor de autorização​

Para completar esta seção, há várias considerações a serem feitas:

A URL do emissor do seu servidor de autorização

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

Como recuperar os metadados do servidor de autorização
  • 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. Consulte a documentação do seu provedor para os endpoints específicos.
Como registrar o MCP inspector como cliente no seu servidor de autorização
  • Se seu servidor de autorização suporta Registro Dinâmico de Cliente, você pode pular esta etapa, pois o MCP inspector se registrará automaticamente como cliente.
  • Se seu servidor de autorização não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente no seu servidor de autorização.
Entenda os parâmetros de solicitação de token

Ao solicitar tokens de acesso de diferentes servidores de autorização, você encontrará várias abordagens para especificar o recurso alvo e permissões. Aqui estão os principais padrões:

  • Baseado em indicador de recurso:

    • Usa o parâmetro resource para especificar a API alvo (veja RFC 8707: Resource Indicators for OAuth 2.0)
    • Comum em implementações modernas de OAuth 2.0
    • Exemplo de solicitação: 
      {
  "resource": "http://localhost:3001",
  "scope": "create:todos read:todos"
}
    • O servidor emite tokens vinculados especificamente ao recurso solicitado

  • Baseado em audiência:

    • Usa o parâmetro audience para especificar o destinatário pretendido do token
    • Semelhante aos indicadores de recurso, mas com semânticas diferentes
    • Exemplo de solicitação: 
      {
  "audience": "todo-api",
  "scope": "create:todos read:todos"
}

  • Baseado apenas em escopo:

    • Depende apenas de escopos sem parâmetros de recurso/audiência
    • Abordagem tradicional do OAuth 2.0
    • Exemplo de solicitação: 
      {
  "scope": "todo-api:create todo-api:read openid profile"
}
    • Frequentemente usa escopos prefixados para namespacing de permissões
    • Comum em implementações OAuth 2.0 mais simples
Melhores práticas
  • Verifique a documentação do seu provedor para os parâmetros suportados
  • Alguns provedores suportam múltiplas abordagens simultaneamente
  • Indicadores de recurso fornecem melhor segurança por restrição de audiência
  • Considere usar indicadores de recurso quando disponíveis para melhor controle de acesso

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

Registre o MCP inspector como cliente​

Integrar o gerenciador de tarefas com o Logto é simples, pois é um provedor OpenID Connect que suporta indicadores de recurso e escopos, permitindo proteger sua API de tarefas com http://localhost:3001 como indicador de recurso.

Como o Logto ainda não suporta Registro Dinâmico de Cliente, você precisará registrar manualmente o MCP inspector como cliente em seu tenant Logto:

  1. Abra seu MCP inspector, vá para a configuração de Autenticação e clique em "OAuth2.0 Flow". Copie o valor do Redirect URI, que deve ser algo como http://localhost:6274/oauth/callback.
  2. Faça login no Logto Console (ou no seu Logto Console auto-hospedado).
  3. Navegue até a aba "Aplicações", clique em "Criar aplicação". No final da página, clique em "Criar app sem framework".
  4. Preencha os detalhes da aplicação e clique em "Criar aplicação":
    • Selecione um tipo de aplicação: Escolha "Aplicação de página única".
    • Nome da aplicação: Insira um nome para sua aplicação, ex: "MCP Inspector".
  5. Na seção "Configurações / Redirect URIs", cole o valor do Redirect URI copiado do MCP inspector. Clique em "Salvar alterações" 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 configuração de Autenticação em "OAuth2.0 Flow" no campo "Client ID".
  8. No campo "Scope", insira: create:todos read:todos delete:todos. Isso garantirá que o token de acesso retornado pelo Logto contenha os escopos necessários para acessar o gerenciador de tarefas.

Configure o MCP Auth​

Primeiro, instale o SDK MCP Auth no seu projeto do servidor MCP.

pnpm add mcp-auth

Agora precisamos inicializar o MCP Auth no seu servidor MCP. Com o modo de recurso protegido, você precisa configurar seus metadados de recurso incluindo os servidores de autorização.

Existem duas formas de configurar servidores de autorização:

  • Pré-busca (Recomendado): Use fetchServerConfig() para buscar os metadados antes de inicializar o MCPAuth. Isso garante que a configuração seja validada na inicialização.
  • Descoberta sob demanda: Forneça apenas issuer e type - os metadados serão buscados sob demanda quando necessário. Isso é útil para runtimes edge (como Cloudflare Workers) onde fetch assíncrono no topo do arquivo não é permitido.

Configure os metadados do recurso protegido​

Primeiro, obtenha a URL do emissor do seu servidor de autorização:

No Logto, você pode encontrar a URL do emissor na página de detalhes da sua aplicação dentro do Logto Console, na seção "Endpoints & Credentials / Issuer endpoint". Deve ser algo como https://meu-projeto.logto.app/oidc.

Agora, configure os Metadados do Recurso Protegido ao construir a instância do MCP Auth:

// todo-manager.ts

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

const issuerUrl = '<issuer-url>'; // Substitua pela URL do emissor do seu servidor de autorização

// Defina o identificador do recurso para este servidor MCP
const resourceId = 'http://localhost:3001';

// Pré-busca da configuração do servidor de autorização (recomendado)
const authServerConfig = await fetchServerConfig(issuerUrl, { type: 'oidc' });

// Configure o MCP Auth com os metadados do recurso protegido
const mcpAuth = new MCPAuth({
  protectedResources: {
    metadata: {
      resource: resourceId,
      authorizationServers: [authServerConfig],
      // Escopos que este servidor MCP entende
      scopesSupported: [
        "create:todos",
        "read:todos",
        "delete:todos"
      ]
    }
  }
});

Atualize o servidor MCP​

Estamos quase lá! É hora de atualizar o servidor MCP para aplicar a rota e o middleware do MCP Auth, depois implementar o controle de acesso baseado em permissões para as ferramentas do gerenciador de tarefas com base nos escopos do usuário.

Agora, aplique as rotas de metadados do recurso protegido para que clientes MCP possam recuperar os metadados esperados do recurso a partir do servidor MCP.

// todo-manager.ts

// Configure as rotas de Metadados do Recurso Protegido
// Isso expõe metadados sobre este servidor de recursos para clientes OAuth
app.use(mcpAuth.protectedResourceMetadataRouter());

Em seguida, aplicaremos o middleware MCP Auth ao servidor MCP. Este middleware irá lidar com a autenticação e autorização das requisições recebidas, garantindo que apenas usuários autorizados possam acessar as ferramentas do gerenciador de tarefas.

// todo-manager.ts

app.use(mcpAuth.protectedResourceMetadataRouter());

// Aplique o middleware MCP Auth
app.use(
  mcpAuth.bearerAuth('jwt', {
    resource: resourceId,
    audience: resourceId,
  })
);

Neste ponto, podemos atualizar as ferramentas do gerenciador de tarefas para aproveitar o middleware MCP Auth para autenticação e autorização.

Vamos atualizar a implementação das ferramentas.

// todo-manager.ts

// outros imports...
import assert from 'node:assert';
import { fetchServerConfig, MCPAuth, MCPAuthBearerAuthError } from 'mcp-auth';
import { type AuthInfo } from '@modelcontextprotocol/sdk/server/auth/types.js';

// Será mencionado na próxima seção
import { TodoService } from './todo-service.js';

const assertUserId = (authInfo?: AuthInfo) => {
  const { subject } = authInfo ?? {};
  assert(subject, 'Informação de autenticação inválida');
  return subject;
};

const hasRequiredScopes = (userScopes: string[], requiredScopes: string[]): boolean => {
  return requiredScopes.every((scope) => userScopes.includes(scope));
};

const todoService = new TodoService();

server.registerTool(
  'create-todo',
  {
    description: 'Criar uma nova tarefa',
    inputSchema: { content: z.string() },
  },
  ({ content }, { authInfo }) => {
    const userId = assertUserId(authInfo);

    /**
     * Apenas usuários com o escopo 'create:todos' podem criar tarefas
     */
    if (!hasRequiredScopes(authInfo?.scopes ?? [], ['create:todos'])) {
      throw new MCPAuthBearerAuthError('missing_required_scopes');
    }

    const createdTodo = todoService.createTodo({ content, ownerId: userId });

    return {
      content: [{ type: 'text', text: JSON.stringify(createdTodo) }],
    };
  }
);

server.registerTool(
  'get-todos',
  {
    description: 'Listar todas as tarefas',
    inputSchema: {},
  },
  (_params, { authInfo }) => {
    const userId = assertUserId(authInfo);

    /**
     * Se o usuário possui o escopo 'read:todos', pode acessar todas as tarefas (todoOwnerId = undefined)
     * Se não possui, pode acessar apenas suas próprias tarefas (todoOwnerId = userId)
     */
    const todoOwnerId = hasRequiredScopes(authInfo?.scopes ?? [], ['read:todos'])
      ? undefined
      : userId;

    const todos = todoService.getAllTodos(todoOwnerId);

    return {
      content: [{ type: 'text', text: JSON.stringify(todos) }],
    };
  }
);

server.registerTool(
  'delete-todo',
  {
    description: 'Excluir uma tarefa pelo id',
    inputSchema: { id: z.string() },
  },
  ({ id }, { authInfo }) => {
    const userId = assertUserId(authInfo);

    const todo = todoService.getTodoById(id);

    if (!todo) {
      return {
        content: [{ type: 'text', text: JSON.stringify({ error: 'Falha ao excluir tarefa' }) }],
      };
    }

    /**
     * Usuários só podem excluir suas próprias tarefas
     * Usuários com o escopo 'delete:todos' podem excluir qualquer tarefa
     */
    if (todo.ownerId !== userId && !hasRequiredScopes(authInfo?.scopes ?? [], ['delete:todos'])) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({ error: 'Falha ao excluir tarefa' }),
          },
        ],
      };
    }

    const deletedTodo = todoService.deleteTodo(id);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            message: `Tarefa ${id} excluída`,
            details: deletedTodo,
          }),
        },
      ],
    };
  }
);

Agora, crie o "serviço de tarefas" usado no código acima para implementar a funcionalidade relacionada:

Crie o arquivo todo-service.ts para o serviço de tarefas:

// todo-service.ts

type Todo = {
  id: string;
  content: string;
  ownerId: string;
  createdAt: string;
};

/**
 * Um serviço simples de tarefas para fins de demonstração.
 * Usa um array em memória para armazenar as tarefas
 */
export class TodoService {
  private readonly todos: Todo[] = [];

  getAllTodos(ownerId?: string): Todo[] {
    if (ownerId) {
      return this.todos.filter((todo) => todo.ownerId === ownerId);
    }
    return this.todos;
  }

  getTodoById(id: string): Todo | undefined {
    return this.todos.find((todo) => todo.id === id);
  }

  createTodo({ content, ownerId }: { content: string; ownerId: string }): Todo {
    const todo: Todo = {
      id: this.genId(),
      content,
      ownerId,
      createdAt: new Date().toISOString(),
    };

    // eslint-disable-next-line @silverhand/fp/no-mutating-methods
    this.todos.push(todo);
    return todo;
  }

  deleteTodo(id: string): Todo | undefined {
    const index = this.todos.findIndex((todo) => todo.id === id);

    if (index === -1) {
      return undefined;
    }

    // eslint-disable-next-line @silverhand/fp/no-mutating-methods
    const [deleted] = this.todos.splice(index, 1);
    return deleted;
  }

  private genId(): string {
    return Math.random().toString(36).slice(2, 10);
  }
}

Parabéns! Implementamos com sucesso um servidor MCP completo com Autenticação (Authentication) e Autorização (Authorization)!

info

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

Checkpoint: Execute as ferramentas todo-manager​

Reinicie seu servidor MCP e abra o MCP inspector no navegador. Ao clicar no botão "Connect", você 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 do checkpoint anterior para executar as ferramentas do gerenciador de tarefas. Desta vez, você poderá usar essas ferramentas com sua identidade de usuário autenticada. O comportamento das ferramentas dependerá dos papéis e permissões atribuídos ao seu usuário:

  • Se você estiver logado como User (com apenas o escopo create:todos):

    • Você pode criar novas tarefas usando a ferramenta create-todo
    • Você só pode visualizar e excluir suas próprias tarefas
    • Você não poderá ver ou excluir tarefas de outros usuários

  • Se estiver logado como Admin (com todos os escopos: create:todos, read:todos, delete:todos):

    • Você pode criar novas tarefas
    • Pode visualizar todas as tarefas do sistema usando a ferramenta get-todos
    • Pode excluir qualquer tarefa usando a ferramenta delete-todo, independentemente de quem a criou

Você pode testar esses diferentes níveis de permissão:

  1. Saindo da sessão atual (clique no botão "Disconnect" no MCP inspector)
  2. Fazendo login com outra conta de usuário que tenha papéis/permissões diferentes
  3. Tentando as mesmas ferramentas novamente para observar como o comportamento muda de acordo com as permissões do usuário

Isso demonstra como o Controle de acesso baseado em papel (RBAC) funciona na prática, onde diferentes usuários têm diferentes níveis de acesso à funcionalidade do sistema.

Resultado da ferramenta do gerenciador de tarefas no MCP inspector

info

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

Notas finais​

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

  • Configuração de um servidor MCP básico com ferramentas de gerenciamento de tarefas (create-todo, get-todos, delete-todo)
  • Implementação de Controle de acesso baseado em papel (RBAC) com diferentes níveis de permissão para usuários e administradores
  • Integração do servidor MCP com um servidor de autorização usando MCP Auth
  • Configuração do MCP Inspector para autenticar usuários e usar tokens de acesso com escopos para chamar ferramentas

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