Desenvolvimento Local MCP

Configure um ambiente de desenvolvimento local para o servidor MCP da Azion, incluindo clonagem, build e deploy de sua própria instância.

Ver como Markdown

Este guia cobre como configurar um ambiente de desenvolvimento local para o servidor MCP da Azion, útil para testes, customização ou contribuição ao projeto.

Pré-requisitos

Antes de começar, certifique-se de ter:

  • Node.js 20+ instalado
  • Yarn gerenciador de pacotes
  • Azion CLI instalado: como baixar
  • Git para clonar o repositório
  • Chave de API OpenAI (necessária para recursos de IA no desenvolvimento local)

Configuração

1. Clonar o repositório

git clone https://github.com/aziontech/mcp-server.git
cd mcp-server

2. Instalar dependências

yarn install

3. Configurar variáveis de ambiente

# Necessário para recursos de IA
export OPENAI_API_KEY="sua_chave_openai"
# Opcional: Autenticação Fast Pass para integração com Azion Copilot
export MCP_COPILOT_SERVER_TOKEN="seu_token"

4. Build do servidor

azion build

Executando localmente

Inicie o servidor de desenvolvimento:

azion dev
# O servidor estará disponível em http://localhost:3333

Conectar seu assistente de código

Uma vez que o servidor esteja rodando, configure seu assistente de código para usar o endpoint local:

# Exemplo com Claude Code
claude mcp add "azion-mcp-local" "http://localhost:3333" -t http -H "Authorization: Bearer SEU_PERSONAL_TOKEN"

Deploy pessoal

Faça deploy de sua própria instância do servidor MCP na Plataforma Azion.

1. Criar configuração pessoal

# Criar diretório de configuração pessoal
mkdir -p azion/personal
# Vincular seu projeto
azion link
# Build com configuração pessoal
azion build --config-dir azion/personal

2. Deploy

azion deploy --config-dir azion/personal

3. Configurar variáveis de ambiente

Após o deploy, adicione as variáveis de ambiente necessárias no Console Azion:

  1. Navegue até sua aplicação no Console Azion
  2. Vá para Variáveis de Ambiente
  3. Adicione OPENAI_API_KEY com sua chave de API OpenAI

4. Usar sua URL pessoal

Atualize sua configuração MCP para usar a URL do seu deploy pessoal em vez do endpoint de produção.

Testes

Usando o MCP Inspector

Teste seu deploy local ou pessoal com o MCP Inspector:

# Instalar MCP Inspector
npm install -g @modelcontextprotocol/inspector
# Executar o inspector
npx @modelcontextprotocol/inspector

Na interface do Inspector:

  1. Selecione streamable-http como tipo de transporte
  2. Digite sua URL: http://localhost:3333 (local) ou sua URL de deploy pessoal
  3. Adicione o header de autenticação: Authorization: Bearer SEU_PERSONAL_TOKEN
  4. Clique em Connect e teste as ferramentas disponíveis

Testar diretamente com Node.js

npx @modelcontextprotocol/inspector node build/index.js

Estrutura do projeto

O projeto do servidor MCP está organizado da seguinte forma:

Diretório/ArquivoDescrição
src/index.tsPonto de entrada principal
src/core/Funcionalidade central
src/core/tools.tsDefinições de ferramentas
src/core/resources.tsDefinições de recursos
src/core/prompts.tsDefinições de prompts
src/middlewares/auth.tsMiddleware de autenticação
src/helpers/utils.tsFunções auxiliares
azion/productionConfiguração do ambiente de produção
azion/stageConfiguração do ambiente de stage

Diretórios de configuração

O projeto inclui diretórios de configuração predefinidos:

  • azion/production: Configuração do ambiente de produção
  • azion/stage: Configuração do ambiente de stage
  • azion/personal: Sua configuração pessoal (crie este)

Nunca modifique os diretórios production ou stage. Sempre use uma configuração pessoal para desenvolvimento.

Métodos de autenticação

O servidor MCP suporta múltiplos métodos de autenticação:

MétodoDescriçãoFormato
Fast Pass TokenToken interno para Azion CopilotDefinido via variável de ambiente MCP_COPILOT_SERVER_TOKEN
Personal TokensPersonal Tokens AzionFormato: azion[a-zA-Z0-9]{35} (40 caracteres)
OAuth TokensBearer tokens do fluxo OAuth SSOValidado contra /oauth/userinfo
JWT TokensBearer tokens para autenticação API v4Validado contra /v4/account/auth/token

Ordem de detecção de token: JWT primeiro para Bearer tokens, depois OAuth se JWT falhar.

Solução de problemas no desenvolvimento local

Servidor não inicia

  1. Verifique a versão do Node.js: node --version (deve ser 20+)
  2. Verifique se a porta 3333 está disponível
  3. Certifique-se de que todas as dependências estão instaladas: yarn install

Erros de autenticação

  1. Verifique se seu Personal Token é válido
  2. Verifique se OPENAI_API_KEY está definido corretamente
  3. Certifique-se de que o formato do header de autorização está correto

Falhas no build

# Limpar e reconstruir
rm -rf build/
azion build

Próximos passos