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

Seu próprio cliente

Conecte qualquer cliente MCP ao Nodaro por Streamable HTTP, descubra o servidor OAuth, registre o cliente ou um app de desenvolvedor e faça login com PKCE.

Seu próprio cliente pode se conectar ao Nodaro se falar MCP padrão por Streamable HTTP e fizer login com OAuth. Aponte-o para https://mcp.nodaro.ai/mcp, deixe que ele descubra o servidor OAuth, registre-o e leve o usuário pela tela de consentimento. Esta página lista os endpoints, as regras de registro e a validade dos tokens.

O que seu cliente precisa

  • MCP por Streamable HTTP em https://mcp.nodaro.ai/mcp.
  • Fluxo de código de autorização do OAuth 2.0 com PKCE. Só o método de code challenge S256 é aceito.
  • Descoberta OAuth pelos metadados do recurso protegido (RFC 9728) e pelos metadados do servidor de autorização (RFC 8414).
  • Um registro de cliente, pelo Dynamic Client Registration (RFC 7591) ou como um app de desenvolvedor que você registra uma vez.

Endpoints

O quêOnde
Endpoint do MCPhttps://mcp.nodaro.ai/mcp
Metadados do recurso protegidohttps://mcp.nodaro.ai/.well-known/oauth-protected-resource
Metadados do servidor de autorizaçãohttps://app.nodaro.ai/.well-known/oauth-authorization-server
Dynamic Client RegistrationPOST https://app.nodaro.ai/v1/oauth/register
Troca de tokenPOST https://app.nodaro.ai/v1/oauth/token
Revogação de tokenPOST https://app.nodaro.ai/v1/oauth/revoke

Os dois documentos de metadados são servidos nos dois hosts, app.nodaro.ai e mcp.nodaro.ai. Cada um também é servido com o sufixo /mcp, por exemplo /.well-known/oauth-protected-resource/mcp, porque alguns clientes testam essa forma primeiro. Os metadados do servidor de autorização anunciam os endpoints de autorização, token, registro e revogação, o tipo de resposta code, a concessão authorization_code, PKCE com S256, a autenticação client_secret_post e os escopos aceitos.

Em uma implantação que serve o MCP por caminho, tudo isso fica no host ao qual você se conecta. O endpoint é https://<host>/v1/mcp. O desafio 401 dele indica o documento de metadados em resource_metadata: https://<host>/.well-known/oauth-protected-resource/v1/mcp. O emissor e o endpoint de registro ficam em https://<host>. Veja MCP por caminho.

O fluxo de conexão

Descobrir o servidor de autorização

Leia os metadados do recurso protegido no host do MCP. Eles vinculam o recurso https://mcp.nodaro.ai/mcp ao servidor de autorização dele, https://app.nodaro.ai. Depois, leia os metadados do servidor de autorização para obter os endpoints.

Registrar o cliente

Envie o seu client_name e as URIs de redirecionamento ao endpoint de registro. O Nodaro responde com um client_id que começa com ndr_dcr_ e um client_secret. O endpoint aceita 10 requisições por minuto de um mesmo endereço IP.

Abra o endpoint de autorização no navegador com o seu client_id, o redirect_uri, response_type=code, a lista de scope, um state aleatório e o code_challenge do PKCE com code_challenge_method=S256. O usuário faz login, revisa as permissões e clica em Permitir.

Trocar o código

O Nodaro redireciona para o seu redirect_uri com um code e o seu state. Confira o state e depois troque o código no endpoint de token com o seu code_verifier. Um código funciona uma única vez e expira 10 minutos depois de emitido.

Chamar o endpoint do MCP

Envie o token de acesso, que começa com ndr_app_, como Authorization: Bearer <token> em toda requisição para https://mcp.nodaro.ai/mcp. Liste as ferramentas com tools/list.

Um cliente Streamable HTTP também pode abrir um GET no endpoint MCP, com Accept: text/event-stream, para receber mensagens que o servidor inicia. O servidor do Nodaro nunca inicia uma: cada requisição é respondida na própria resposta, então um cliente que não abre a transmissão não perde nada. A transmissão fica em silêncio depois dos cabeçalhos da resposta. Um proxy ou uma reinicialização do servidor pode fechá-la quando ela está ociosa, então abra-a de novo quando isso acontecer. Um GET sem text/event-stream no cabeçalho Accept é respondido com 406.

Quais nomes de cliente podem se registrar

Por padrão, o Dynamic Client Registration aceita apenas nomes de clientes conhecidos: Claude, Claude Code, Cursor, Cline, Continue, Goose, ChatGPT, OpenAI, Lovable, Gemini, Gemini CLI, Codex, MCP Inspector e mcp-inspector. Um cliente com outro nome recebe 403 client_not_allowed.

Se o seu cliente tem outro nome, registre-o uma vez como app de desenvolvedor:

  1. Abra app.nodaro.ai/settings/developer-apps e clique em Criar app.
  2. Informe o nome, as URIs de redirecionamento e os escopos que o cliente pode pedir.
  3. Copie o client_id e o client_secret. O segredo aparece uma única vez. Ele não expira, e você pode substituí-lo por um novo na página do app.

Cada conta pode registrar manualmente até 5 apps de desenvolvedor. Os clientes que se registraram sozinhos aparecem na mesma lista, mas não contam para esse limite.

Na sua própria instância do Nodaro, o operador controla o registro com MCP_DYNAMIC_REGISTRATION (allowlist, o padrão, open ou off) e MCP_DCR_ALLOWLIST. No modo open, cada par de nome de cliente e URI de redirecionamento pode ter no máximo 5 registros não usados em 24 horas; os seguintes retornam 429 too_many_open_registrations. No modo off, o registro retorna 403 dcr_disabled. Veja MCP em uma instalação auto-hospedada.

Uma implantação que lista os clientes MCP dela em MCP_ALLOWED_CLIENT_IDS não aceita nenhum cliente autorregistrado. O registro responde 403 dcr_disabled, e só os clientes que a implantação criou podem fazer login ou chamar o endpoint do MCP. Veja Solução de problemas para saber o que cada passo retorna.

O aplicativo da própria implantação, sem tela de consentimento

Em uma implantação que lista os clientes MCP dela, o aplicativo da própria implantação pode pular a tela de consentimento quando também faz o login dos usuários, como o provedor de SSO externo da implantação. O operador ativa isso para o cliente do aplicativo. O servidor do aplicativo então troca uma asserção assinada por um token de acesso do MCP:

  1. O operador entrega ao seu servidor três valores: o seu client_id, o seu segredo do cliente e a audiência de troca do provedor.
  2. Quando uma pessoa precisa do MCP, o seu servidor assina uma asserção para essa pessoa. Ele usa HS256, aud definido como a audiência de troca, um jti novo e uma validade de um ou dois minutos.
  3. O seu servidor envia a asserção para POST /v1/oauth/token com grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer e indica o endpoint do MCP como resource.
  4. O seu servidor chama o endpoint do MCP com o token como Authorization: Bearer <token>. Por padrão, o token dura uma hora (expires_in), e não há token de atualização. Troque uma nova asserção antes de a hora terminar, ou depois de um 401.

Mantenha todos esses valores no seu servidor. O segredo do cliente e o segredo do provedor, juntos, conseguem obter um token para qualquer pessoa que o provedor consiga autenticar. Os metadados do servidor de autorização listam a concessão jwt-bearer em grant_types_supported somente onde a troca está ativa.

Tokens

  • Validade. Um token de acesso dura 90 dias. Não há tokens de atualização: quando uma chamada retornar 401, leve o usuário pela tela de consentimento de novo.
  • Revogação. Seu cliente pode revogar um token no endpoint de revogação, que sempre responde 200. O usuário também pode revogar seu cliente em Configurações › Apps conectados, em app.nodaro.ai/settings/connected-apps. Isso encerra na hora todos os tokens emitidos para o cliente em nome desse usuário, e sua próxima chamada retorna 401.
  • A tela de consentimento. Como um cliente registrado dinamicamente escolheu o próprio nome, a tela de consentimento avisa o usuário de que o Nodaro não verificou esse nome.

O mesmo servidor OAuth atende a API REST. OAuth para desenvolvedores explica tudo em detalhes.

Tratar os resultados das ferramentas

  • Tarefas. As ferramentas de geração iniciam uma tarefa e retornam o ID dela na hora. Consulte get_job periodicamente, a cada 5 a 10 segundos, ou chame wait_for_job, até a tarefa estar completed ou failed. Veja Ferramentas de tarefa.
  • Conteúdo estruturado. Muitas ferramentas retornam os dados como structuredContent junto com a resposta em texto, por exemplo o envelope da tarefa de get_job. Leia os dados estruturados no código.
  • Os cartões são opcionais. Hosts que exibem MCP Apps recebem cartões interativos, como o progresso de uma tarefa e os seletores de upload. Um cliente sem eles lê os mesmos resultados como texto e dados estruturados.
  • API tasks. Um cliente compatível com a API tasks do MCP recebe o progresso das tarefas por ela.
  • Ferramentas ausentes. Uma ferramenta cujo escopo o usuário não concedeu fica de fora de tools/list. Confira os escopos concedidos antes de procurar uma ferramenta que falta.

Erros comuns

  • Usar https://app.nodaro.ai/mcp. Esse endereço é uma página web. Um POST nele retorna 405 com o código de erro wrong_mcp_host, que informa a URL correta.
  • Usar https://api.nodaro.ai/mcp. Esse domínio não existe.
  • Adicionar uma barra no final. Use exatamente https://mcp.nodaro.ai/mcp.

Referência

Perguntas frequentes

Qual transporte o servidor MCP do Nodaro usa?

Streamable HTTP, em https://mcp.nodaro.ai/mcp. O login é OAuth 2.0 com PKCE, e um cliente pode se registrar sozinho com o Dynamic Client Registration.

Por que o registro falha com client_not_allowed?

O registro dinâmico aceita apenas nomes de clientes conhecidos, e o nome do seu cliente não está na lista. Em vez disso, registre um app de desenvolvedor nas suas configurações do Nodaro e use o ID do cliente e o segredo dele.

Quanto tempo dura um token de acesso do servidor MCP do Nodaro?

90 dias. Não há tokens de atualização; por isso, depois de 90 dias o usuário faz login de novo. Seu cliente pode revogar um token antes disso, e o usuário pode revogar o cliente em Configurações › Apps conectados.

Posso testar o servidor MCP do Nodaro com o MCP Inspector?

Sim. MCP Inspector é um dos nomes de cliente que podem se registrar dinamicamente; por isso, ele consegue se conectar, fazer login e listar as ferramentas.

Última atualização

Nesta página