Odysseus AI MCP: configuracao de servidores, OAuth e diagnostico

O que MCP significa dentro de um espaco Odysseus

Model Context Protocol (MCP) e um protocolo para que uma aplicacao de IA descubra e chame ferramentas expostas por um servidor. O servidor pode oferecer documentos em leitura, consulta de calendario, pesquisa ou uma acao como criar uma tarefa. Ele define o esquema e o comportamento da ferramenta; o host decide quando conectar, o que exibir e se uma pessoa precisa aprovar a chamada.

Em uma configuracao Odysseus AI MCP, nao trate modelo, espaco e processo MCP como uma unica zona de confianca. Um modelo local pode rodar no seu computador enquanto um servidor MCP envia uma consulta para uma API hospedada. Um servidor remoto pode estar fora da sua rede mesmo quando a interface Odysseus esta local. Registre esse limite antes de adicionar credenciais ou arquivos privados.

Antes da configuracao: autenticacao, administrador e limites de rede

A orientacao oficial do Odysseus coloca o gerenciamento MCP e os tokens de API na area de administrador. Entre com uma conta autorizada e confirme que o deploy carregou as mesmas variaveis usadas pelo processo web. Um chat funcionando no navegador nao prova que o processo do servidor consegue chegar a um endpoint MCP.

Mantenha a autenticacao durante os testes. Abrir uma rota administrativa sem login ou expor uma porta de modelo pode virar uma superficie esquecida. Se Odysseus roda em Docker, callback e nome de servico precisam ser acessiveis pela rede do container, nao apenas pelo navegador do host. Confira DNS, TLS, firewall e origem permitida.

Revisar servidores MCP integrados e o cache do npx

Odysseus documenta servidores MCP integrados como um ponto de partida. Mesmo assim, o comando precisa existir no ambiente, o processo precisa iniciar com os argumentos corretos e o servidor precisa acessar seu runtime. Uma entrada integrada e um atalho de registro, nao uma prova de saude.

Alguns exemplos usam um pacote npx a partir de um cache local. O primeiro inicio pode resolver o pacote e os seguintes usar a copia armazenada. Confirme pacote e versao permitidos. Em um host isolado, prepare um cache aprovado ou instale o comando localmente em vez de repetir uma busca que nao alcanca o registro.

1. Escolher entrada de baixo risco

   Prefira listar um recurso de teste ou documento. Evite shell e acesso amplo a arquivos.

2. Conferir o ambiente

   Execute o comando na mesma imagem ou container do Odysseus e remova segredos do stderr.

3. Verificar resolucao npx

   Confirme cache ou registro permitido e revise a versao resolvida.

npx -y @playwright/mcp@latest --help

docker compose logs --tail=120 odysseus

Adicionar um servidor MCP remoto com OAuth

Um servidor remoto com OAuth adiciona uma troca de identidade ao transporte e ao handshake. O host Odysseus inicia a autorizacao, o usuario concede os escopos e o provedor devolve o navegador ao callback registrado. Esse callback precisa resolver para a base publica conhecida pelo provedor; localhost dentro de um container nao ajuda um navegador remoto.

O guia de configuracao do Odysseus documenta OAUTH_REDIRECT_BASE_URL para servidores MCP remotos com OAuth. Defina o valor no limite do deploy, mantenha esquema e caminho estaveis e reinicie o servico que le as variaveis. Nunca cole client secret em pagina, prompt, captura ou JSON versionado. Redirect e escopos devem seguir a documentacao do provedor.

1. Confirmar o callback

   Anote a rota HTTPS e os escopos exatos na documentacao do servidor.

2. Definir OAUTH_REDIRECT_BASE_URL

   Adicione o valor ao ambiente do deploy e reinicie o processo.

3. Autorizar pelo Odysseus

   Comece o fluxo no Odysseus e confira o retorno para host e caminho esperados.

OAUTH_REDIRECT_BASE_URL=https://mcp.example.com/oauth/callback

Usar um caminho de teste repetivel

Repita a mesma sequencia sempre que adicionar ou mudar um servidor Odysseus AI MCP: saude do espaco, processo do servidor, handshake e depois uma ferramenta com entrada conhecida. A ordem separa falhas de inferencia, transporte, permissao e provedor em vez de esconder tudo como erro de conexao.

Registre um resultado concreto: nome do servidor e da ferramenta, formato dos argumentos, status, duracao e identificador seguro da requisicao. Remova tokens, cabecalhos, documentos privados e prompts completos. Em caso de falha, guarde o esquema e uma amostra redigida, nunca o payload privado.

1. Verificar saude do Odysseus

   Confirme web e dependencias antes de abrir a area MCP.

2. Verificar o processo

   Compare comando, transporte, ambiente e endpoint com os logs.

3. Listar ferramentas e esquemas

   Confira nomes, argumentos obrigatorios e capacidades de leitura ou escrita.

Corrigir servidores inacessiveis, permissoes e registros antigos

Comece pela camada que falhou. Se o processo nao inicia, revise comando, pacote, diretorio e ambiente. Se inicia mas nenhuma ferramenta aparece, revise transporte e handshake. Se ferramentas aparecem mas a chamada falha, confira argumentos, escopo OAuth, cota e endpoint. Um modelo que ignora a ferramenta tambem pode indicar problema no host ou no ciclo de tool calling.

A rede de containers causa muitos falsos erros MCP. Um nome que funciona no navegador pode nao resolver dentro do container. Teste o endpoint no mesmo runtime, confira certificados e politica de saida e use o nome do servico ou gateway correto. Mantenha portas de modelo e servico privadas por padrao.

Aplicar uma checklist pratica para tokens e rede

MCP torna capacidades combinaveis; por isso a configuracao mais segura e a menor que resolve a tarefa. Conceda somente pastas, dominios e acoes necessarios. Prefira leitura, exija aprovacao visivel para escrita e planeje a rotacao de tokens OAuth e API. Um processo local ainda pode enviar dados para um provedor externo.

Proteja o limite do deploy tanto quanto o segredo. Mantenha autenticacao, use HTTPS em callbacks, restrinja admin e nao publique portas brutas. Se uma ferramenta precisa de rede privada, permita somente o host e a porta necessarios. Nunca coloque segredos no repositorio, prompt, captura, URL ou relatorio.

• Use conta ou espaco de teste na primeira conexao.
• Revise e mantenha rastreaveis comandos e versoes de pacotes.
• Guarde credenciais no ambiente ou em um gerenciador de segredos.
• Limite pastas, dominios e ferramentas ao minimo necessario.
• Mascare tokens, documentos privados e prompts completos nos logs.