Skip to main content
Glama
marcelomarkus

Workshop MCP

by marcelomarkus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Workshop MCP

TDC Workshop

Este projeto foi desenvolvido durante o workshop do evento TDC - community.

Sobre o workshop

Repositório com o passo a passo, código-fonte e exercícios para construir seu primeiro servidor baseado no Model Context Protocol (MCP).

Durante o workshop, foram apresentados:

  • A arquitetura cliente-servidor do protocolo MCP;

  • A criação e exposição de ferramentas (tools) para LLMs;

  • O gerenciamento de recursos (resources) e prompts dinâmicos;

  • A conexão do servidor a clientes reais de IA.

O projeto principal foi criado com Python e FastMCP. Ele disponibiliza ferramentas e recursos para consultar a previsão do tempo e demonstra uma operação que pede confirmação antes de enviar convites.

Related MCP server: MCP Weather Server

Requisitos

  • Python 3.14 ou superior;

  • uv instalado;

  • Uma aplicação configurada no Auth0;

  • Acesso à internet para consultar https://wttr.in;

  • Um cliente MCP compatível, como OpenCode ou MCP Inspector.

O projeto usa uv.lock para manter as versões das dependências reproduzíveis.

Instalação

Clone o repositório e entre na pasta do projeto:

git clone https://github.com/marcelomarkus/tdc-workshop-mcp.git
cd tdc-workshop-mcp

Sincronize as dependências. O comando cria ou atualiza o ambiente virtual .venv automaticamente:

uv sync

Confira a versão do Python selecionada:

python --version
uv python find

Configuração do Auth0

O servidor principal usa Auth0Provider e precisa destas variáveis de ambiente:

Variável

Descrição

AUTH_DOMAIN

Domínio da instância Auth0

CLIENT_ID

Identificador da aplicação

CLIENT_SECRET

Segredo da aplicação

AUDIENCE

Identificador da API configurada no Auth0

Crie o arquivo local de configuração a partir do modelo:

cp .env_example .env

Preencha o .env com valores reais:

AUTH_DOMAIN=https://seu-dominio.auth0.com
CLIENT_ID=seu-client-id
CLIENT_SECRET=seu-client-secret
AUDIENCE=https://sua-api

O arquivo .env não é carregado automaticamente pelo Python. Exporte as variáveis antes de iniciar o servidor:

set -a
source .env
set +a

Ou defina-as diretamente na mesma chamada:

AUTH_DOMAIN="https://seu-dominio.auth0.com" \
CLIENT_ID="seu-client-id" \
CLIENT_SECRET="seu-client-secret" \
AUDIENCE="https://sua-api" \
uv run main.py

Nunca compartilhe o CLIENT_SECRET nem o inclua em commits.

Executando o servidor

Com as variáveis carregadas, inicie o servidor principal:

uv run main.py

O endpoint MCP fica disponível em:

http://127.0.0.1:8000/mcp

Mantenha o processo em execução enquanto o cliente MCP estiver conectado. Para encerrá-lo, pressione Ctrl+C.

Executando o MCP Inspector

O MCP Inspector fornece uma interface web para testar tools, resources e prompts.

Em um primeiro terminal, inicie o servidor:

set -a
source .env
set +a
uv run main.py

Em outro terminal, execute o Inspector:

npx @modelcontextprotocol/inspector

Abra http://localhost:6274 no navegador e configure:

Campo

Valor

Transport

Streamable HTTP

URL

http://127.0.0.1:8000/mcp

Clique em Connect e teste as ferramentas e os recursos disponíveis. As variáveis do Auth0 precisam estar no ambiente do processo do servidor.

Conectando pelo OpenCode

O arquivo opencode.json já aponta para o endpoint local:

{
  "mcp": {
    "Workshop": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Com o servidor rodando, abra o OpenCode neste projeto.

Funcionalidades disponíveis

Tools

  • Tempo(cidade): consulta o tempo atual de uma cidade;

  • Temperatura(cidade): consulta a temperatura atual de uma cidade;

  • Enviar_Convites(quantidade): solicita confirmação e simula o envio, reportando o progresso de cada item.

As consultas meteorológicas usam wttr.in/<cidade>?format=%t.

Resources

  • workshop://oque-o-mcp-nao-e: texto introdutório sobre MCP;

  • previsao://{cidade}: previsão de uma cidade informada na URI.

Prompt

  • exemplo_prompt(pergunta): orienta a escolha entre as tools meteorológicas.

Estrutura do projeto

.
├── main.py          # Servidor MCP principal
├── mcp_com_api.py   # Servidor MCP gerado a partir da API Petstore
├── exercises/       # Exercícios progressivos do workshop
│   ├── 01-mcp-server/
│   ├── 02-resources/
│   ├── 03-tools/
│   ├── 04-prompts/
│   ├── 05-Context/
│   ├── 06-auth/
│   └── 07-mcp-api/
├── slide/            # Material de apoio
│   └── tdc-workshop-mcp.pdf
├── opencode.json    # Configuração do OpenCode
├── pyproject.toml   # Metadados e dependências
├── uv.lock          # Versões resolvidas
└── .env_example     # Modelo das variáveis do Auth0

Desenvolvimento

Você pode executar o projeto pelo modo Debug do VS Code ou pelo uv:

uv run main.py

Para verificar a sintaxe dos módulos:

python -m compileall main.py mcp_com_api.py exercises

Solução de problemas

ModuleNotFoundError

Execute uv sync e rode o programa com uv run main.py, evitando o Python global quando as dependências estiverem instaladas apenas em .venv.

Erros de autenticação

Verifique se as quatro variáveis do Auth0 foram exportadas no mesmo ambiente do servidor e se o domínio inclui o protocolo esperado.

Falha na consulta meteorológica

Teste a conectividade com:

curl "https://wttr.in/Sao%20Paulo?format=%t"

Porta 8000 ocupada

Libere a porta ou ajuste a porta no servidor e no opencode.json, mantendo o mesmo endereço nos dois lados.

Documentação e referências

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers