MCP Server + Asgardeo

Um servidor MCP de exemplo que utiliza Asgardeo para autenticação e conexão de clientes.

Documentação

Model Context Protocol (MCP) Server + Asgardeo

Este é um exemplo de servidor Model Context Protocol (MCP) que permite que clientes MCP remotos se conectem e autentiquem usando o Asgardeo.

O Asgardeo autentica usuários que acessam o servidor MCP e permite que você controle o acesso às ferramentas com base em permissões de nível de aplicativo e de organização definidas para cada usuário.

O servidor MCP é alimentado por Cloudflare Workers:

Atua como servidor OAuth Server para seus clientes MCP
Atua como Cliente OAuth/OIDC para sua organização Asgardeo

Introdução

Antes de começar, certifique-se de ter os seguintes pré-requisitos:

Conta Asgardeo.
Instale o Node.js versão 18.x ou superior no seu sistema.
Uma Cloudflare conta para implantação

Configurar o Asgardeo

Primeiro, faça login no console do Asgardeo e navegue até Applications > New Application.

Em seguida, selecione Traditional Web Application e conclua o assistente fornecendo o nome e a URL de redirecionamento autorizada indicados abaixo. (Certifique-se de que o protocolo permaneça definido como OpenID Connect (OIDC).)

Nome do aplicativo: CloudflareMCPServer
URL de redirecionamento autorizada: http://localhost:8788/callback

Nota - O http://localhost:8788/callback é usado apenas durante os testes locais; a URL de callback da implantação do Cloudflare será adicionada em uma etapa posterior.

Anote os seguintes valores nas abas Protocol e Info do aplicativo registrado.

client-id da aba Protocol.
client-secret da aba Protocol.
Nome da sua organização Asgardeo

Desenvolvimento e Testes Locais

Clone o repositório diretamente e instale as dependências usando as instruções fornecidas abaixo.


# Clone the repository
git clone https://github.com/sagara-gunathunga/cloudflare-mcp-asgardeo

# Move to the demo project directory
cd demo-mcp-server

## Install dependencies
npm install

Em seguida, crie um arquivo .dev.vars na raiz do seu projeto com os seguintes valores.

# .dev.vars
ASGARDEO_CLIENT_ID=<client-id from the previous step>
ASGARDEO_CLIENT_SECRET=<client-secret from the previous step>
ASGARDEO_BASE_URL=https://api.asgardeo.io/t/<Asgardeo organization name>
ASGARDEO_SCOPE=openid profile email roles

Desenvolver e Testar

Execute o servidor localmente para disponibilizá-lo em http://localhost:8788

npm run dev

Para autenticar com o Asgardeo, você deve primeiro ter uma conta de usuário criada. Se ainda não o fez, siga este guia para criar um usuário no Asgardeo.

Em seguida, inicie o MCP Inspector localmente usando o seguinte comando.

npx @modelcontextprotocol/inspector

Para testar o servidor local, altere o Transport Type para SSE e insira http://localhost:8788/sse no Inspector e clique em conectar. Depois de seguir as instruções, você poderá autenticar com o Asgardeo e usar recursos como "List Tools" no Inspector. Ao invocar a ferramenta userInfo, você deverá ver resultados semelhantes ao exemplo mostrado na captura de tela abaixo.

Alternativamente, você pode testar usando o Cloudflare Workers AI LLM Playground. Basta inserir http://localhost:8787/sse como URL do servidor MCP e clicar em Connect. Isso redirecionará você para a página de login do Asgardeo. Depois de concluir o processo de login, você poderá interagir com o LLM no Playground e usar as ferramentas definidas no seu servidor MCP.

Por exemplo, tente perguntar ao LLM: "Quem sou eu?"

Implantando no Cloudflare

Primeiro, crie um namespace KV no Cloudflare usando o seguinte comando.

npx wrangler kv namespace create OAUTH_KV

Certifique-se de atualizar o arquivo wrangler.jsonc com o valor id recebido após executar o comando acima.

"kv_namespaces": [
  {
    "binding": "OAUTH_KV",
    "id": "<your-kv-id>"
  }
],

Em seguida, defina os seguintes segredos via Wrangler executando os seguintes comandos.

npx wrangler@latest secret put ASGARDEO_CLIENT_ID
npx wrangler@latest secret put ASGARDEO_CLIENT_SECRET
npx wrangler@latest secret put ASGARDEO_BASE_URL
npx wrangler@latest secret put ASGARDEO_SCOPE
npx wrangler@latest secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

Você pode usar os valores armazenados no arquivo .dev.vars com o comando acima.

Implantar e Testar

Implante o servidor MCP para disponibilizá-lo no seu domínio workers.dev.

npx wrangler@latest deploy

Anote a URL do Cloudflare Worker recém-criada, que é exibida como saída quando você executa o comando de implantação. Você também pode encontrar essa URL fazendo login no console web do Cloudflare. A URL do Worker normalmente segue este formato: https://remote-mcp-asgardeo.<your-subdomain>.workers.dev

Em seguida, você precisa configurar uma URL de callback usando a URL do Worker acima. A URL de callback completa deve ter o seguinte formato.

https://remote-mcp-asgardeo.<your-subdomain>.workers.dev/callback

Para configurá-la:

Faça login no Console do Asgardeo.
Navegue até o aplicativo que você criou.
Vá para a aba Protocol.
Adicione o valor acima em Authorized redirect URLs para que o Asgardeo possa reconhecê-lo como uma URL de redirecionamento válida.

A URL de conexão do servidor MCP que implantamos no Cloudflare tem o seguinte formato.

https://remote-mcp-asgardeo.<your-subdomain>.workers.dev/sse

Para testar o servidor remoto, altere o Transport Type para SSE e insira https://remote-mcp-asgardeo.<your-subdomain>.workers.dev/sse no Inspector e clique em conectar. Depois de seguir as instruções, você poderá autenticar com o Asgardeo e usar recursos como "List Tools" no Inspector. Ao invocar a ferramenta userInfo.

Alternativamente, você pode testar usando o Cloudflare Workers AI LLM Playground. Basta inserir https://remote-mcp-asgardeo.<your-subdomain>.workers.dev/sse como URL do servidor MCP e clicar em Connect. Isso redirecionará você para a página de login do Asgardeo. Depois de concluir o processo de login, você poderá interagir com o LLM no Playground e usar as ferramentas definidas no seu servidor MCP.

Por exemplo, tente perguntar ao LLM: "Quem sou eu?"

Usando Cursor e outros clientes MCP

Para conectar o Cursor ao seu servidor MCP, escolha Type: "Command" e no campo Command, combine os campos de comando e argumentos em um único campo (por exemplo, npx mcp-remote https://<your-worker-name>.<your-subdomain>.workers.dev/sse).

Observe que, embora o Cursor suporte servidores HTTP+SSE, ele não suporta autenticação, então você ainda precisa usar mcp-remote (e usar um servidor STDIO, não um HTTP).

Você pode conectar seu servidor MCP a outros clientes MCP, como o Windsurf, abrindo o arquivo de configuração do cliente, adicionando o mesmo JSON usado na configuração do Claude e reiniciando o cliente MCP.

Controle de Acesso

Este servidor MCP usa Asgardeo tanto para autenticação quanto para controle de acesso.

Todos os usuários autenticados têm acesso à ferramenta userInfo.
Usuários com a função manager podem acessar a ferramenta getDirectReportees. Para outros, esta ferramenta não ficará visível.

Para suportar esse cenário de acesso baseado em funções, o Asgardeo retorna as funções do usuário para usuários autenticados, permitindo que o servidor MCP avalie as permissões de acordo.

Para testar isso:

Crie uma nova função chamada manager no Asgardeo.
Atribua a função a um usuário seguindo este guia.
Certifique-se de que as funções do usuário estejam configuradas para serem retornadas como atributos no token de ID ou no endpoint de informações do usuário, seguindo as instruções de configuração relevantes aqui.

Acessar o servidor MCP remoto a partir do Claude Desktop

Abra o Claude Desktop e navegue até Settings -> Developer -> Edit Config. Isso abre o arquivo de configuração que controla quais servidores MCP o Claude pode acessar.

Substitua o conteúdo pela seguinte configuração. Depois de reiniciar o Claude Desktop, uma janela do navegador será aberta mostrando sua página de login OAuth. Conclua o fluxo de autenticação para conceder ao Claude acesso ao seu servidor MCP. Após conceder o acesso, as ferramentas ficarão disponíveis para uso.

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp-github-oauth.<your-subdomain>.workers.dev/sse"
      ]
    }
  }
}

Assim que as ferramentas (em 🔨) aparecerem na interface, você pode pedir ao Claude para usá-las.