NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações

MCP em uma instalação auto-hospedada

Ative o servidor MCP de um Nodaro auto-hospedado para que Claude, Cursor, ChatGPT e outros clientes MCP usem a instalação por OAuth, num host ou caminho MCP.

O servidor MCP do Nodaro permite que clientes de IA como Claude, Cursor, Cline, Continue, Goose e ChatGPT usem as ferramentas da sua instalação auto-hospedada em nome de um usuário. Ele vem desativado por padrão. Para ativá-lo, você dá ao MCP um nome de host próprio, direciona esse nome de host para a API e define duas variáveis. Os usuários, então, fazem login na sua instalação com OAuth a partir do cliente deles.

Como o MCP é servido

  • A API serve o MCP no caminho /mcp, na porta 9000 dentro do contêiner nodaro.
  • O servidor web na porta 3000 recusa requisições MCP. Uma requisição a /mcp no endereço principal do app responde 405, com o erro wrong_mcp_host e o endereço do endpoint real.
  • Por isso, o MCP precisa de um nome de host próprio, como mcp.nodaro.example.com, cujo tráfego chegue diretamente à API. Nas edições Business e Cloud, você pode servi-lo por caminho nos seus próprios hosts.
  • O login continua no seu domínio principal. O documento de descoberta OAuth /.well-known/oauth-authorization-server e a tela de consentimento são servidos em PUBLIC_URL.

Ativar o MCP

Direcionar um nome de host MCP para a API

Crie um registro DNS para mcp.<your-domain> que aponte para o seu servidor. Não passe esse registro pelo proxy de uma CDN: os proxies quebram as conexões de Server-Sent Events de longa duração que o MCP usa.

O arquivo do Compose não publica a porta da API. Publique-a na interface de loopback, no serviço nodaro:

  nodaro:
    ports:
      - "3000:3000"
      - "127.0.0.1:9000:9000"

Depois, dê ao seu proxy reverso um segundo site para o host MCP, que encaminhe para 127.0.0.1:9000 em vez de 127.0.0.1:3000. Mantenha o buffering das respostas desligado, como no exemplo do nginx.

Adicione o nome de host MCP como um domínio personalizado do serviço backend:

railway domain add mcp.your-domain.com --service backend

Ou, no painel do Railway: Project › backend service › Settings › Domains › Add custom domain. Depois, adicione o registro CNAME no seu provedor de DNS.

Definir as variáveis

MCP_ENABLED=true                              # required; the default is off
MCP_PUBLIC_URL=https://mcp.your-domain.com    # the hostname from step 1

No conjunto de serviços do Compose, adicione as duas em environment: do serviço nodaro: o arquivo do Compose não as repassa do .env. Depois, rode docker compose -f docker-compose.community.yml up -d.

MCP_PUBLIC_URL é a identidade que os endpoints de descoberta anunciam para o recurso protegido (RFC 9728) e a base dos links de upload que as ferramentas retornam. Sem ela, a sua instalação anuncia o host MCP do Nodaro Cloud. Se você servir o MCP no seu domínio principal em vez de um subdomínio, defina essa variável com o mesmo valor de PUBLIC_URL. Nesse caso, as requisições a /mcp ainda precisam chegar diretamente à porta da API.

Verificar os endpoints de descoberta

curl https://mcp.your-domain.com/.well-known/oauth-protected-resource
curl https://your-domain.com/.well-known/oauth-authorization-server

Os dois precisam retornar JSON com o status 200.

Adicionar o conector no seu cliente

O endpoint MCP é https://mcp.your-domain.com/mcp. No Claude, abra Settings › Connectors › Add custom connector e digite essa URL. Para outros clientes, veja Conectar um cliente e use a sua própria URL do MCP em vez da URL do Nodaro Cloud.

MCP por caminho (sem host MCP dedicado)

Só nas edições Business e Cloud. É uma chave do perfil de superfície, que a Community ignora. Uma implantação sem nome de host sobrando para mcp.<your-domain>, ou cuja rede só permite os próprios hosts listados, pode servir o mesmo endpoint MCP sob um caminho:

NODARO_SURFACE_PROFILE={"mcp":{"byPath":true}}
  • Onde responde. Em https://<host>/v1/mcp, em cada host que a implantação declara como seu: PUBLIC_URL e cada entrada de CORS_ORIGIN. mcp.path define outro caminho: /v1/mcp ou um caminho em minúsculas abaixo dele, sem barra no final e com até 64 caracteres. Qualquer outro caminho volta para /v1/mcp, com um aviso.
  • O que precisa. MCP_ENABLED=true e PUBLIC_URL definido com o endereço da própria implantação. Sem PUBLIC_URL, o servidor registra um aviso e mantém o MCP em /mcp.
  • Sem mudança no proxy. O proxy incluído já encaminha /v1/* e /.well-known/oauth-* para a API. O MCP_PUBLIC_URL também não é necessário.
  • Todo endereço segue o host. O desafio 401, os documentos de descoberta do OAuth, a tela de consentimento e os links que as ferramentas entregam indicam o host declarado pelo qual o cliente se conectou. As pessoas fazem login no site em que estão. Uma requisição em um host que a implantação não declarou recebe os endereços de PUBLIC_URL.
  • Um login vale para todos os hosts. Um cliente que fez login por um dos hosts da implantação pode usar o mesmo token em outro.
  • O caminho substitui /mcp. Com o modo ligado, /mcp e os documentos /.well-known/…/mcp dele não são servidos. Um cliente configurado com um endereço /mcp anterior se reconecta pelo caminho.

Liste em CORS_ORIGIN só as origens que esta implantação serve: cada uma conta como um host próprio enquanto o modo está ligado. Com o modo desligado, o padrão, nenhuma resposta do MCP muda.

Para conferir:

curl https://your-domain.com/.well-known/oauth-protected-resource/v1/mcp

O resource precisa ser https://your-domain.com/v1/mcp. As pessoas então adicionam https://your-domain.com/v1/mcp como URL do conector.

Quais clientes podem se registrar

Os clientes MCP fazem login com OAuth. Os clientes compatíveis se registram na sua instalação por registro dinâmico de clientes (RFC 7591). Duas variáveis controlam esse registro, e os padrões delas servem para a maioria das instalações:

VariávelPadrãoO que faz
MCP_DYNAMIC_REGISTRATIONallowlistallowlist só aceita os nomes de cliente de MCP_DCR_ALLOWLIST. open aceita qualquer cliente. off desativa o registro dinâmico.
MCP_DCR_ALLOWLIST14 clientes conhecidosOs nomes de cliente aceitos no modo allowlist, separados por vírgula.

A lista de permissões padrão é: Claude, Claude Code, Cursor, Cline, Continue, Goose, ChatGPT, OpenAI, Lovable, Gemini, Gemini CLI, Codex, MCP Inspector e mcp-inspector. Para adicionar o seu próprio cliente, defina a lista completa:

MCP_DCR_ALLOWLIST=Claude,Cursor,Cline,Continue,Goose,YourCustomClient

allowlist é o modo recomendado. Quando MCP_ALLOWED_CLIENT_IDS está definida, o registro dinâmico responde como off, não importa o que essas variáveis digam. Veja MCP só pelo seu próprio cliente.

MCP só pelo seu próprio cliente

Uma instalação pode deixar o endpoint MCP dela acessível só pelos clientes que ela mesma configurou, por exemplo a própria aplicação de chat. As pessoas fazem login pelo login da sua instalação e aprovam o cliente uma vez na tela de consentimento. Todas as edições leem uma variável:

MCP_ALLOWED_CLIENT_IDS=app_0123456789abcdef0123456789abcdef

É uma lista de client_ids de apps de desenvolvedor, separados por vírgula. A lista guarda IDs, e não nomes, porque qualquer cliente pode escolher o próprio nome, mas só a sua instalação gera um client_id. Cada entrada precisa ser o ID de um app de desenvolvedor: app_ e 32 caracteres hexadecimais minúsculos. Qualquer outra entrada, como um ID autorregistrado ndr_dcr_…, impede a inicialização e indica a posição da entrada. Não definida ou vazia, não há lista. Reinicie para aplicar uma mudança.

Com uma lista definida:

  • O endpoint MCP só aceita um token de acesso emitido para um app de desenvolvedor ativo e listado. Qualquer outra credencial é recusada com 403 mcp_client_not_allowed: um token de outro cliente, uma sessão com login ou um token de API pessoal. A recusa não indica nenhum cliente. Uma requisição sem token ainda recebe o desafio 401 de sempre, para que os clientes encontrem o login.
  • A verificação acontece em toda chamada. Depois de um reinício que remove um cliente da lista, os tokens dele param de funcionar no endpoint MCP na próxima chamada. Se o cliente não puder ser consultado, a chamada é recusada com 503 mcp_client_check_failed.
  • O login recusa qualquer outro cliente que peça MCP, antes da tela de consentimento. A pessoa volta direto ao cliente com error=unauthorized_client. Um app de desenvolvedor que não está na lista e não pede MCP ainda faz login para a API REST, mas o token dele é recusado no endpoint MCP.
  • O registro dinâmico de clientes responde 403 dcr_disabled, como com MCP_DYNAMIC_REGISTRATION=off.
  • O Workflow Copilot continua funcionando. Ele executa as mesmas ferramentas dentro do servidor e não é um cliente MCP do endpoint.

Os tokens de acesso duram 90 dias, e não há token de atualização. Um novo token sempre passa pelo login, ou pela troca de asserção para a única aplicação que você indicar para ela.

Para configurar um cliente para a sua própria aplicação de chat:

Deixar só os administradores gerenciarem apps de desenvolvedor

Na edição Business, defina {"developerApps":{"manage":"admin"}} no perfil de superfície. Assim, os únicos clientes que podem fazer o login das pessoas são os que você cria.

Criar o cliente

Com login como administrador, abra Configurações › Apps de desenvolvedor ou chame POST /v1/developer-apps. Informe o callback da sua aplicação de chat em redirectUris e os escopos de que ela precisa em scopesRequested. Copie o client_id e o segredo do cliente, que é mostrado uma vez só.

Listar o cliente e reiniciar

Defina MCP_ALLOWED_CLIENT_IDS com o client_id, e MCP_DYNAMIC_REGISTRATION=off para deixar claro. Reinicie o backend.

Configurar a sua aplicação de chat

Informe a ela o endereço do MCP, o client_id, o segredo ou PKCE e o callback dela. Os usuários dela fazem login pela sua instalação e aprovam o app uma vez.

Qualquer outro cliente MCP, como o Claude.ai ou o Cursor, é mandado de volta com unauthorized_client no login, ou recebe 403 mcp_client_not_allowed se já tiver um token. Veja a Solução de problemas do MCP.

MCP sem clique de consentimento: a troca de asserção

Quando a sua aplicação de chat também é o provedor de identidade com que as suas pessoas fazem login, o servidor dela pode obter um token MCP para qualquer uma delas sem tela de consentimento. O provedor é um provedor assertion do login único. O servidor assina uma asserção que indica a pessoa e a troca em POST /v1/oauth/token, com a concessão JWT-bearer da RFC 7523. Para o lado do cliente no OAuth, veja Apps OAuth.

A troca fica desligada a menos que estas três coisas estejam definidas, e então ela só fica ligada para o cliente que você indicar:

  1. MCP_ALLOWED_CLIENT_IDS lista o cliente da aplicação. O cliente precisa ser um app de desenvolvedor confidencial, com segredo. Um cliente só com PKCE não pode usar a troca.
  2. MCP_ASSERTION_EXCHANGE_CLIENT_IDS indica o client_id da aplicação. Toda entrada também precisa estar em MCP_ALLOWED_CLIENT_IDS, senão a inicialização é interrompida.
  3. exchangeAudience está definido na entrada do provedor em EXTERNAL_SSO_PROVIDERS. A aplicação coloca esse valor no aud das asserções de troca dela. Ele precisa ser diferente da audience de login do provedor, e só um provedor pode defini-lo. Veja Campos do provedor.

Clientes indicados sem nenhum provedor que defina exchangeAudience impedem a inicialização. Um provedor com um exchangeAudience e nenhum cliente indicado fica simplesmente desligado, então limpar uma variável desliga a troca.

MCP_ALLOWED_CLIENT_IDS=app_0123456789abcdef0123456789abcdef
MCP_ASSERTION_EXCHANGE_CLIENT_IDS=app_0123456789abcdef0123456789abcdef
MCP_ASSERTION_EXCHANGE_TOKEN_TTL_SECONDS=3600   # optional: 300 to 86400
EXTERNAL_SSO_PROVIDERS=@/etc/nodaro/sso-providers.json
# in that file, the provider's entry gains:  "exchangeAudience": "nodaro-mcp-exchange"

Onde a troca está desligada, POST /v1/oauth/token responde a essa concessão como um tipo de concessão desconhecido. Onde ela está ligada, os metadados do servidor de autorização listam urn:ietf:params:oauth:grant-type:jwt-bearer em grant_types_supported.

  • As mesmas verificações do login. A asserção é verificada como uma asserção de login, contra a audiência de troca. Cada jti é aceito uma vez só, somando o login e a troca. A pessoa é encontrada pelas mesmas regras de vinculação de contas.
  • Pessoas novas ganham uma conta. Quando o provedor afirma um e-mail verificado que não tem conta, uma conta é criada e vinculada, como em um primeiro login.
  • O token. Um token de app comum para essa pessoa, com os escopos que a aplicação pede, nunca mais amplos que os scopesRequested do cliente. Ele vale por MCP_ASSERTION_EXCHANGE_TOKEN_TTL_SECONDS, uma hora por padrão. Não há token de atualização: a aplicação faz a troca de novo.
  • Apps conectados. Em Configurações › Apps conectados, a pessoa vê o app como Conectado pelo seu login. Se a pessoa revogar o app ali, os tokens dele param na hora, e a troca não emite nenhum token novo para ela. Só o próprio consentimento dela, pelo login comum, conecta o app de novo.
  • Limites. 300 trocas por minuto por rede, e 300 por cliente. Acima de qualquer um dos dois, a resposta é 429 com Retry-After. A troca precisa do Redis e responde 503 quando o Redis não pode ser alcançado.
  • Registros. Uma linha de registro por troca indica o cliente e o resultado, e a pessoa quando um token foi emitido. Ela nunca contém a asserção, um token ou um segredo.

Com a troca ligada, a sua aplicação obtém um token para qualquer pessoa que o seu provedor afirmar, sem um clique dessa pessoa. O secret do provedor e o segredo do cliente, juntos, são uma chave para todas as contas em que o provedor consegue fazer login. Mantenha os dois só no servidor da sua aplicação, nunca em um navegador ou em um app de celular. Troque-os se qualquer um deles puder ter vazado: o segredo do cliente em Configurações › Apps de desenvolvedor, o segredo do provedor em EXTERNAL_SSO_PROVIDERS, com um reinício. Diga às suas pessoas o que a aplicação faz com a conta delas, porque elas não veem nenhuma tela de consentimento.

O que os clientes podem fazer

O servidor MCP cobre as ferramentas de geração de imagem, vídeo, áudio, personagens, locais e objetos, e as ferramentas da galeria, dos workflows, dos apps, dos componentes salvos e dos modelos. Cada usuário age como a própria conta na sua instalação.

A lista de ferramentas acompanha o que a instalação oferece. O perfil de superfície pode restringir nós, modelos, mundos ou importações por link, e um administrador pode desligar um nó. Então, uma sessão MCP só lista uma ferramenta quando tudo de que ela precisa é oferecido ao usuário dessa sessão. Uma chamada a uma ferramenta que não está na lista é recusada com o mesmo erro que uma execução recebe, como 403 node_not_available, antes de qualquer criação. As ferramentas que leem os próprios dados do usuário, executam workflows ou apps salvos ou fornecem documentação são sempre listadas. Veja Listas de permissões.

Veja a Referência das ferramentas MCP e a Solução de problemas do MCP.

Perguntas frequentes

O MCP vem ativado por padrão em um Nodaro auto-hospedado?

Não. Defina MCP_ENABLED=true e MCP_PUBLIC_URL, direcione um nome de host MCP para a API e reinicie. No conjunto de serviços do Compose, adicione as duas variáveis no bloco environment do serviço nodaro, porque o arquivo do Compose não as repassa do .env.

Por que o meu cliente MCP recebe 405 wrong_mcp_host?

O cliente usa o endereço principal do app, onde o servidor web recusa requisições MCP. Aponte o cliente para o host MCP, https://your-mcp-host/mcp, que precisa alcançar a API na porta 9000 diretamente.

Quais clientes MCP podem se registrar na minha instalação?

Por padrão, 14 clientes conhecidos, entre eles Claude, Claude Code, Cursor, Cline, Continue, Goose, ChatGPT e Codex. Adicione nomes a MCP_DCR_ALLOWLIST, ou defina MCP_DYNAMIC_REGISTRATION=open para aceitar qualquer cliente.

Posso servir o MCP sem um nome de host próprio para ele?

Nas edições Business e Cloud, sim. Defina mcp.byPath como true no perfil de superfície, e o MCP responde em https://your-host/v1/mcp nos próprios hosts da implantação. Nenhuma mudança no proxy e nenhum MCP_PUBLIC_URL são necessários.

Posso permitir que só a minha própria aplicação de chat use o MCP?

Sim. Crie um app de desenvolvedor para ela, liste o client_id dele em MCP_ALLOWED_CLIENT_IDS e reinicie. Todo outro cliente MCP é recusado no login, e um token de qualquer outro cliente recebe 403 mcp_client_not_allowed.

Posso colocar uma CDN na frente do host MCP?

Não uma que faça proxy do tráfego. O MCP mantém abertas conexões de Server-Sent Events de longa duração, e uma CDN que faz proxy as quebra. Aponte o DNS diretamente para o seu servidor.

Última atualização

Nesta página