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/azion-copilot-api.git
cd azion-copilot-api/mcp

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ó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)

Métodos de autenticação

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

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

• Guia de Configuração MCP
• Exemplos MCP
• Solução de Problemas MCP