Como conectar o MCP Server da Nvoip ao Codex

OAuth compartilhado e descoberta

O servidor MCP usa https://mcp.nvoip.com.br/mcp e anuncia https://api.nvoip.com.br/auth como servidor OAuth. Use a descoberta do cliente, PKCE e consentimento; no Claude, informe somente a URL, deixe Client ID/Secret vazios e clique em Connect. A audiência e os escopos do MCP são próprios: o token MCP não é um token genérico da API v3. Para integrar a API por backend, consulte o guia v3. Respeite a expiração informada em expires_in.

Este artigo explica como conectar o MCP Server da Nvoip ao Codex para consultar métricas e relatórios dentro do ambiente de desenvolvimento.

Importante: o MCP Server está disponível para clientes no Plano Pro e para revendedores Tier IV, V e VI. Usuários secundários precisam ter a permissão MCP Server habilitada no painel.

1. Quando usar com Codex

É indicado para equipes técnicas, suporte e operações que usam Codex para validar dados, investigar integrações e cruzar contexto de produto com informações autorizadas.

2. Antes de começar

Requisito	Detalhe
Plano	Conta no Plano Pro ou revendedor Tier IV, V ou VI.
Permissão	Usuário principal Pro pode acessar. Usuários secundários precisam da permissão MCP Server.
Cliente MCP	Codex ou ambiente compatível com servidor MCP remoto.
Autenticação	OAuth: o cliente MCP abre o login da Nvoip no navegador e renova o acesso sozinho. Não é preciso gerar token no painel.

3. Dados de conexão

Campo	Valor
URL do servidor MCP	`https://mcp.nvoip.com.br/mcp`
Autenticação	OAuth (login da Nvoip no navegador). Token colado à mão só para testes: vale 24 horas e depois para de funcionar.
Comandos	`codex mcp add nvoip --url https://mcp.nvoip.com.br/mcp` e `codex mcp login nvoip`
Metadados OAuth	`https://api.nvoip.com.br/auth/.well-known/oauth-authorization-server`
Recurso protegido	`https://mcp.nvoip.com.br/.well-known/oauth-protected-resource/mcp`

4. Passo a passo

Confira no painel da Nvoip se sua conta é elegível ao MCP Server. Não é preciso gerar token.
No Codex, abra Settings e acesse MCP servers.
Adicione um servidor chamado Nvoip MCP com a URL do MCP Server.
No terminal, rode codex mcp add nvoip --url https://mcp.nvoip.com.br/mcp e depois codex mcp login nvoip; conclua o login da Nvoip no navegador.
No app ou na extensão do IDE, adicione o servidor com a URL e clique em Authenticate quando pedir login. Não preencha Bearer token env var.
Salve, ative o servidor e abra uma nova conversa para carregar as ferramentas.

5. Perguntas de exemplo

Liste as ferramentas MCP disponíveis da Nvoip.
Qual é meu perfil de acesso no MCP?
Traga um resumo de atendimento da minha conta no mês.
Mostre meu consumo MCP e possíveis excedentes.

6. Problemas comuns

Sintoma	O que verificar
Erro de autenticação	Reconecte pelo OAuth. Se você colou um token, ele venceu (24 horas): remova o header e use o login.
Ferramentas não aparecem	Salve a configuração e reinicie a conversa ou o cliente MCP.
Acesso negado	Plano, permissão do usuário e escopo da conta autenticada.
Dados incompletos	Período consultado, canal analisado, histórico disponível e limites aplicáveis.

Atenção: não preencha Bearer token env var nem NVOIP_MCP_BEARER_TOKEN. Um token colado à mão vale 24 horas e depois o Codex passa a receber erro de autenticação. Se você já tinha configurado assim, remova a variável e rode codex mcp login nvoip.

7. Boas práticas de segurança

Não cole access token, refresh token, napikey ou usertoken em prompts, conversas públicas ou documentos compartilhados.
Prefira o login OAuth; se usar token para testes, só no campo seguro de autenticação do cliente MCP.
Revogue ou substitua o token se ele for exposto.
Revise periodicamente quais usuários têm permissão para usar o MCP Server.