Como você protege seu servidor MCP com OAuth dois ponto um usando Scalekit e Alpha Vantage

Ouça este artigo

Protegendo seu servidor MCP com OAuth 2.1 usando Scalekit

Neste artigo você vai aprender a proteger seu servidor MCP com OAuth 2.1 via Scalekit. Vamos montar um servidor de análise de sentimento de ações usando FastAPI, proteger rotas com um middleware que valida tokens Bearer e expor o endpoint de metadata que o Scalekit usa para descobrir seu recurso. Também veremos como a Alpha Vantage fornece notícias e resumos de ações. No fim, seu servidor estará pronto para receber requisições autenticadas de forma simples e segura.

Para entender melhor o contexto do MCP, vale revisar o protocolo de contexto do modelo MCP e suas implicações práticas.

Principais passos:

• Usar Scalekit para expor o endpoint de metadata e gerenciar OAuth 2.1.

• Criar .env e config.py com ALPHAVANTAGEAPI_KEY e metadados do recurso.

• Implementar middleware que valide tokens Bearer via Scalekit.

• Montar o servidor FastAPI e servir /.well-known/oauth-protected-resource/mcp.

• Testar com o MCP Inspector usando um token Bearer.

---

Antes de começar — requisitos

Você vai precisar:

• Node.js (para rodar o MCP Inspector).

• Python 3.10 (para o servidor).

• Bibliotecas Python: FastAPI, uvicorn, requests, e o cliente/SDK do Scalekit.

• Conta no Scalekit.

• Chave da Alpha Vantage (gratuita).

• Editor de texto e terminal.

Observação: o Scalekit centraliza a parte complexa do OAuth. Você só expõe o metadata endpoint e valida tokens no middleware. Se quiser entender abordagens para centralizar ferramentas e fluxos, consulte o guia sobre como centralizar suas ferramentas de trabalho.

---

Criar o recurso no Scalekit

No painel do Scalekit:

• Crie um novo recurso (resource).

• Crie a permissão principal/escopo news:read — descrição: usar Alpha Vantage para obter sentimento de notícias.

• Anote o resource identifier (aparecerá no claim aud do token).

• Guarde o Resource Metadata JSON gerado (contém authorization servers, scopes, docs, resource id).

• Gere credenciais (client id e client secret) para testes.

Dica: para testes locais, exponha o endpoint em /mcp e mantenha a barra no final para evitar erros de descoberta.

---

Permissões e escopos

• Crie e use o scope news:read.

• Seu servidor deve checar que o token possui aud correto e contém o scope news:read.

---

Variáveis de ambiente (.env)

Crie .env e mantenha seguro. Exemplo de variáveis:

Variável	Exemplo
ALPHAVANTAGEAPIKEY	sua-chave-alpha-vantage
METADATAJSONRESPONSE	JSON que o Scalekit devolveu
SCALEKITENVIRONMENTURL	https://app.scalekit.io
SCALEKITCLIENTID	client-id-gerado
SCALEKITCLIENTSECRET	client-secret-gerado
SCALEKITRESOURCEMETADATAURL	https://seu-servidor/.well-known/oauth-protected-resource/mcp
SCALEKITAUTHORIZATIONSERVERS	lista dos authorization servers
SCALEKITAUDIENCENAME	valor do aud (ex: res880563…)
SCALEKITRESOURCENAME	nome do recurso
SCALEKITRESOURCEDOCSURL	URL com a documentação do MCP

Exemplo curto:

• ALPHAVANTAGEAPI_KEY=ABCD1234XYZ

• SCALEKITAUDIENCENAME=res_88056357768398086

• SCALEKITRESOURCEMETADATA_URL=http://localhost:10000/.well-known/oauth-protected-resource/mcp

Nunca comite client secret ou API key no repositório.

---

Arquivo de configuração (config.py)

Crie config.py para:

• Carregar .env (ex: python-dotenv).

• Exportar ALPHAVANTAGEAPIKEY, SCALEKITCLIENTID, SCALEKITCLIENTSECRET, SCALEKITAUDIENCENAME, METADATAJSON_RESPONSE, etc.

• Definir host/porta padrão (ex: localhost, 10000).

Benefício: centralizar variáveis sensíveis e trocar ambientes sem alterar código.

---

Lógica de sentimento (finance.py)

Responsabilidades:

• Receber um ticker (ex: AAPL).

• Chamar Alpha Vantage com ALPHAVANTAGEAPI_KEY.

• Buscar notícias, calcular um sentiment_score simples e retornar as três principais entradas.

• Para cada artigo, extrair: title, summary, source, published_at.

• Retornar JSON claro: ticker, sentimentscore, toparticles[].

Boas práticas:

• Validar ticker.

• Tratar limites da Alpha Vantage (cache e retry).

• Simplificar saída: ticker, sentimentscore, toparticles.

Se você estiver montando um pipeline de processamento de texto mais avançado (pré-processamento, vetorização, normalização), pode aproveitar o tutorial sobre como criar um pipeline de análise de texto para estruturação e testes.

---

Middleware de autorização (AuthMiddleware)

Funções principais:

• Permitir rotas públicas (ex: /.well-known/oauth-protected-resource/mcp).

• Para rotas protegidas, exigir header Authorization: Bearer .

• Se sem token → devolver 401 Unauthorized com JSON explicativo.

• Se token presente → validar via SDK do Scalekit ou endpoint de introspecção:

• Verificar active, exp, aud.

• Confirmar scope contém news:read.

• Em caso de token válido → injetar claims/usuário na request e seguir.

• Em caso de inválido → 401 com mensagem estruturada.

Inclua logs em pontos-chave: token ausente, inválido, validação bem-sucedida.

Observação: você não precisa gerenciar fluxos de emissão/refresh — o Scalekit cuida disso.

---

Servidor MCP (server.py)

Montagem com FastAPI:

• Importar FastAPI, CORS, AuthMiddleware, finance.py.

• Configurar CORS (em dev liberar; em produção restringir).

• Definir lifespan para iniciar/encerrar recursos (ex: clients HTTP, cache).

• Expor o metadata endpoint:
  /.well-known/oauth-protected-resource/mcp — retorna o JSON que o Scalekit espera (authorization servers, bearer method, resource name, docs URL, supported scopes).

• Adicionar AuthMiddleware ao app.

• Definir endpoint de análise (ex: POST /analyze ou POST /news/sentiment) que chama finance.py.

Quando o servidor sobe, o Scalekit e clientes MCP descobrem seu recurso via metadata. Requisições autenticadas passam pelo middleware.

---

Rodando o servidor

Comando:

• uvicorn server:app --host 127.0.0.1 --port 10000 --reload
  App disponível: http://localhost:10000/
  Metadata: http://localhost:10000/.well-known/oauth-protected-resource/mcp

Se usar frameworks que adicionam /mcp automaticamente, confira a barra final.

---

Testando com o MCP Inspector (Node.js)

• Instale Node.js e rode o MCP Inspector.

• Informe a URL do seu servidor (ex: http://localhost:10000/mcp).

• Sem credenciais: Connection Error ou 401 Unauthorized.

• No Inspector, cole o Bearer token gerado no Scalekit.

• Erros comuns: URL sem barra final, aud diferente, scope ausente, CORS.

---

Como o Scalekit simplifica

Você não precisa implementar:

• Fluxo completo (authorization code, PKCE, refresh tokens).

• Armazenamento e verificação manual de assinaturas.

Você deve:

• Expor o metadata endpoint.

• Implementar middleware que valida token via Scalekit.

• Controlar scopes e aud para autorizar acesso.

Para entender melhor práticas técnicas relacionadas à construção de contexto e integração com modelos, consulte o artigo sobre engenharia de contexto em modelos de linguagem.

---

Exemplo resumido do Resource Metadata

Campos principais do JSON do Scalekit:

• resource_name

• resourceid (resXXXX)

• authorization_servers (URLs de token/introspecção)

• scopes_supported (ex: ["news:read"])

• documentation_url

• metadata_url (sua rota /.well-known/…)

Armazene no .env ou em variáveis separadas.

---

Estrutura de arquivos sugerida

• .env — variáveis sensíveis.

• config.py — carregar variáveis e constantes.

• finance.py — lógica de chamadas à Alpha Vantage.

• auth_middleware.py — validação via Scalekit.

• server.py — FastAPI app, metadata endpoint, montagem.

• requirements.txt — dependências (FastAPI, uvicorn, requests, pydantic, scalekit-client).

• package.json — se usar ferramentas Node para testes.

---

Erros comuns e soluções rápidas

• Token inválido → verifique aud e scopes.

• Metadata não encontrado → confirme rota /.well-known/oauth-protected-resource/mcp e barra final.

• CORS bloqueando → ajuste regras no FastAPI.

• Rate limit Alpha Vantage → implemente cache e trate 429.

• Connection Error no Inspector → verifique porta, endpoint /mcp e configuração do proxy token no Scalekit.

Se quiser aprofundar práticas de privacidade e proteção de dados ao lidar com tokens e informações sensíveis, consulte o material sobre como proteger seus dados pessoais com novas tecnologias de privacidade.

---

Segurança e boas práticas

• Nunca coloque client secrets no repositório.

• Use HTTPS em produção.

• Limite scopes ao mínimo (ex: news:read).

• Faça logs, mas não grave tokens inteiros.

• Tenha políticas de CORS restritivas em produção.

• Escreva testes automatizados para o middleware.

Para monitoramento de respostas e comportamento de agentes em pipelines de IA (útil ao auditar chamadas e respostas da Alpha Vantage/processamento), considere práticas como as apresentadas no texto sobre rastrear respostas de agentes com MLflow.

---

Fluxo resumido de uma requisição

• Cliente MCP chama rota protegida.

• Middleware verifica se a rota é pública; caso contrário, exige header Authorization.

• Middleware valida token via Scalekit (introspecção ou SDK).

• Se válido → handler executa (finance.py consulta Alpha Vantage).

• Retorna JSON com resultado ao cliente.

Valide sempre: active, aud, scopes e exp.

---

Exemplo de resposta esperada (formato simplificado)

Ao pedir sentimento para AAPL, retorno conceitual:

• ticker: "AAPL"

• sentiment_score: 0.72

• toparticles: [ { title, summary, source, publishedat }, … ]

Mantenha o JSON simples e consistente.

---

Como validar o token com Scalekit (visão geral)

Duas opções:

• Usar o SDK do Scalekit (recomendado): instanciar cliente com SCALEKITCLIENTID e SCALEKITCLIENTSECRET e chamar validação.

• Fazer chamada HTTP ao endpoint de introspecção listado no metadata e checar active, scope, aud, exp.

Em ambos os casos verifique: token ativo, aud igual a SCALEKITAUDIENCENAME, e scope news:read.

---

Checklist rápido

• [ ] Criou conta no Scalekit.

• [ ] Criou recurso e anotou resource id.

• [ ] Criou scope news:read.

• [ ] Gerou client id e client secret.

• [ ] Criou .env com variáveis.

• [ ] Implementou config.py.

• [ ] Implementou finance.py.

• [ ] Implementou auth_middleware.py.

• [ ] Montou server.py com metadata endpoint.

• [ ] Rodou servidor e testou com MCP Inspector.

• [ ] Verificou logs e ajustou erros.

---

Próximos passos práticos

• Criar .env e carregar variáveis.

• Implementar config.py.

• Escrever finance.py com chamadas à Alpha Vantage e tratamento de limites.

• Implementar AuthMiddleware que valida tokens via Scalekit.

• Montar FastAPI em server.py, expor metadata e proteger rotas.

• Rodar e testar com MCP Inspector.

• Ajustar logs, CORS e cache antes de produção.

---

Conclusão

Você tem agora um roteiro para proteger seu servidor MCP usando Scalekit OAuth 2.1: exponha o metadata endpoint, implemente um middleware que valida tokens, e integre a lógica de sentimento via Alpha Vantage em um FastAPI organizado. O Scalekit gerencia o fluxo de autenticação; você foca na lógica de negócio. Cuide do .env, valide aud e scopes (como news:read) e teste com o MCP Inspector.

Se quiser explorar as novas fronteiras e aplicações relacionadas à síntese e privacidade de dados, o artigo sobre síntese condicional de dados pode trazer insights úteis.

Quer aprofundar? Leia mais no blog: https://blog.aidirectory.com.br

---

Perguntas Frequentes

• Como eu configuro o .env e o config.py para o servidor MCP?
  Crie .env com ALPHAVANTAGEAPIKEY, SCALEKITCLIENTID, SCALEKITCLIENTSECRET, SCALEKITENVIRONMENTURL, SCALEKITRESOURCEMETADATAURL, SCALEKITAUDIENCENAME, SCALEKITRESOURCENAME e SCALEKITRESOURCEDOCS_URL. No config.py carregue essas variáveis (ex: python-dotenv) e exponha objetos simples para o app.

• Como o middleware de autorização protege meus endpoints?
  Adicione um AuthMiddleware que permite caminhos públicos (/.well-known/) e exige Authorization: Bearer nos demais. O middleware valida o token via cliente Scalekit ou introspecção e retorna 401 com JSON se inválido.

• Como eu configuro a permissão news:read no Scalekit?
  No painel do Scalekit, crie a permission/escopo news:read com descrição apropriada e associe ao recurso na criação. Use esse scope nas regras de acesso.

• Como validar o campo aud e o metadata do recurso?
  Aponte SCALEKITRESOURCEMETADATAURL no .env para o JSON do Scalekit. No middleware verifique que o claim aud do token coincide com SCALEKITAUDIENCE_NAME e que o issuer está presente na metadata.

• Como testar localmente com MCP Inspector e Alpha Vantage?
  Rode o servidor (uvicorn server:app --host 127.0.0.1 --port 10000 --reload). No MCP Inspector informe http://localhost:10000/mcp, cole o Bearer token gerado no Scalekit e faça chamadas. Garanta que ALPHAVANTAGEAPI_KEY esteja no .env.

Se você quiser conhecer outros artigos semelhantes a Como você protege seu servidor MCP com OAuth dois ponto um usando Scalekit e Alpha Vantage, você pode visitar a categoria Notícias e Tendências.