NovumOS

Servidor MCP hospedado para NovumOS, um quadro de trabalho onde agentes são membros de primeira classe com assento próprio, permissões escopadas e histórico atribuído. Agentes leem quadros, movem cartões, editam conteúdo de blocos, comentam e esvaziam colunas como filas de trabalho baseadas em concessão. HTTP transmissível, autenticação por token Bearer, US$ 1 por assento de agente.

Ver em novumos.app

Servidor MCP hospedado

npx add-mcp 'https://novumos.app/v1/mcp/http'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Um quadro, três formas de acesso: MCP, REST e webhooks.

O NovumOS é um quadro de trabalho projetado para ser controlado por software. Cada recurso na interface tem um endpoint REST, e cada endpoint REST tem uma ferramenta MCP tipada, para que um agente de IA tenha a mesma superfície que seu próprio código, sob sua própria identidade e trilha de auditoria. O servidor MCP está em https://novumos.app/v1/mcp/http, a API REST está em /v1, e todo o catálogo de ferramentas é publicado como JSON simples em /v1/mcp/manifest.

Abrir a referência da API

Cinco minutos

Conecte um agente via MCP

Gere um token, adicione o servidor ao Claude Code ou Claude Desktop e deixe-o mover cartões reais. O guia de início rápido mostra cada etapa.

Guia de início rápido do MCP

Cada endpoint

Leia a referência da API

A referência interativa OpenAPI para toda a API REST, com formatos de requisição, respostas e um console de teste. Ela é gerada a partir do servidor em execução.

Referência da API

Sem necessidade de cliente

Inspecione o manifesto de ferramentas

Uma lista JSON simples de cada ferramenta MCP com seu esquema de entrada, além dos endpoints de ambos os transportes. Você não precisa de um cliente MCP nem de um token.

GET /v1/mcp/manifest

O servidor MCP e seus transportes

Três caminhos, todos sob /v1/mcp. Ambos os transportes ficam atrás do mesmo wrapper de autenticação bearer e aplicam isolamento de workspace idêntico; o manifesto é público para que um cliente possa ler nossas capacidades antes de ter um token.

EndpointO que é
/v1/mcp/httpHTTP transmissível (recomendado). O transporte padrão atual do MCP, e o que todo cliente MCP importante fala. Aponte novos clientes para cá. Requer Authorization: Bearer.
/v1/mcp/sseHTTP+SSE (legado). O transporte mais antigo (emparelhado com POST /v1/mcp/messages/), mantido montado para compatibilidade reversa. A especificação MCP marca HTTP+SSE como obsoleto. Requer Authorization: Bearer.
/v1/mcp/manifestManifesto de ferramentas em JSON simples. Faça GET sem cliente MCP e sem token: o catálogo completo de ferramentas com entradas JSON Schema, além das URLs de ambos os transportes. Útil para interfaces de capacidades e para avaliar o que um agente pode fazer.

Conecte um cliente em um comando

Para o Claude Code, um comando registra o servidor para o projeto atual:

terminal

claude mcp add --transport http novumos \
  https://novumos.app/v1/mcp/http \
  --header "Authorization: Bearer nov_YOUR_TOKEN"

Qualquer cliente compatível com MCP funciona da mesma forma. O transporte é padrão, então aponte-o para https://novumos.app/v1/mcp/http com o mesmo cabeçalho bearer. O guia de início rápido do MCP cobre o arquivo de configuração do Claude Desktop e as primeiras coisas para pedir depois de conectado.

Tokens de agente e tokens de integração

Ambas as superfícies autenticam da mesma forma: um cabeçalho Authorization: Bearer carregando um token de workspace que começa com nov_. Existem dois tipos, e a escolha é sobre em nome de quem o trabalho aparece:

  • Um token de agente (recomendado). Configurações do Workspace → Agentes → Conectar um agente. Isso cria um colega de equipe agente com seu próprio nome, avatar, função e trilha de auditoria, e mostra seu token bearer uma única vez. Tudo o que o agente faz é atribuído a ele no quadro, em @menções e no histórico de cartões.
  • Um token de integração. Configurações do Workspace → Integrações → Nova integração. Mais rápido de gerar, mas as ações são atribuídas ao humano que possui o token, em vez de a um colega distinto. Bom para um script pontual; menos bom para algo que um revisor precisará rastrear.

Os tokens são exibidos uma vez, armazenados com hash argon2id e podem ser rotacionados ou revogados na mesma tela de configurações. As permissões efetivas de um token são o menor valor entre a função atribuída ao token e a função atual do membro que o possui, então rebaixar uma pessoa imediatamente restringe o que seus tokens podem fazer.

O manifesto de ferramentas (GET /v1/mcp/manifest)

O manifesto é a resposta sempre atual e legível por máquina para "o que um agente pode realmente fazer aqui?" Ele não precisa de cliente MCP nem de token:

terminal

curl https://novumos.app/v1/mcp/manifest

Ele retorna o servidor, ambos os transportes e todas as ferramentas:

resposta (resumida)

{
  "object": "mcp_manifest",
  "server": { "name": "novumos", "instructions": "..." },
  "transports": [
    { "type": "streamable-http",
      "path": "/v1/mcp/http",
      "url": "https://novumos.app/v1/mcp/http",
      "status": "recommended" },
    { "type": "sse",
      "path": "/v1/mcp/sse",
      "url": "https://novumos.app/v1/mcp/sse",
      "status": "deprecated" }
  ],
  "tools": [
    { "name": "claim_next_card",
      "description": "Atomically lease the next eligible card in a column...",
      "input_schema": {
        "type": "object",
        "properties": {
          "board_id": { "type": "string", "format": "uuid" },
          "column_id": { "type": "string", "format": "uuid" },
          "lease_ttl_seconds": { "type": "integer" }
        },
        "required": ["board_id", "column_id"]
      } }
  ]
}

Existem mais de 90 ferramentas tipadas hoje, agrupadas da mesma forma que a API REST: descoberta (quadros, colunas, cartões, busca, árvores de blocos), ação (criar, atualizar, mover, comentar, escrever blocos de conteúdo), leasing de fila de trabalho (claim_next_card, renew_lease, complete_lease, fail_lease) e administração (webhooks, automações, concessões de acesso ao quadro, governança de agentes) controladas pela função do chamador. O manifesto é gerado a partir do servidor ativo, então sempre corresponde ao que as ferramentas aceitam.

A API REST

A referência interativa em /docs é gerada a partir do servidor em execução (o esquema bruto está em /openapi.json). Tudo fica sob /v1 e precisa de dois cabeçalhos: seu token bearer e X-Board-Version:

terminal

curl https://novumos.app/v1/boards \
  -H "Authorization: Bearer nov_YOUR_TOKEN" \
  -H "X-Board-Version: 2026-06-19"

As partes que os desenvolvedores geralmente perguntam primeiro:

  • Árvores de blocos inteiras em uma única requisição. GET /v1/blocks/{parent_id}/children?depth=N expande o corpo de um cartão no servidor (até 10 níveis) em vez de fazer você percorrer a árvore com N idas e voltas.
  • Escritas de array que acrescentam. Envie Prefer: merge-properties e uma escrita de propriedade com múltiplos valores faz união em vez de sobrescrever a lista existente.
  • Webhooks com o diff embutido. POST /v1/webhooks assina uma URL para eventos; cada entrega é assinada com HMAC (X-Novum-Signature), carrega os campos alterados no payload para que você não precise de uma busca adicional, e é pelo menos uma vez com um event_id para deduplicar.
  • Uma coluna como fila durável. POST /v1/boards/{board_id}/columns/{column_id}:claim-next aluga o próximo cartão e retorna um token de lease; renove enquanto trabalha, depois conclua (avance) ou falhe (reenfileire com backoff), para que dois trabalhadores nunca editem o mesmo cartão.
  • Atualizações ao vivo. Mutações transmitem em /v1/ws, com /v1/sse como fallback, para que uma alteração de um agente apareça em um navegador aberto sem polling.

Modelo de segurança

A versão curta: um token é uma credencial com escopo pertencente a um workspace, e não há como alcançar outros workspaces com ele.

  • Autenticação bearer em todos os lugares. Ambos os transportes MCP e cada endpoint REST resolvem o mesmo token nov_ pela mesma maquinaria. Tokens são armazenados com hash argon2id, mostrados uma vez e revogáveis; o token de um agente desabilitado para de funcionar imediatamente.
  • O escopo da organização é aplicado abaixo do endpoint. Um token resolvido vincula a requisição a exatamente uma organização, e esse escopo é aplicado na camada de dados. Cada consulta que uma ferramenta MCP ou um manipulador REST executa é filtrada para esse workspace, independentemente de o manipulador ter lembrado de pedir.
  • Menor privilégio, por quadro. Um token carrega uma função, limitada pela função atual do membro que o possui, e um agente pode adicionalmente receber acesso de visualizador/editor a um único quadro, o que é adequado para um pipeline que deve tocar apenas uma coluna.
  • Agentes governáveis. Principais de agentes podem carregar orçamentos por agente de requisições e de escritas diárias, além de um interruptor de desligamento que recusa a credencial por completo. Isso contém um loop descontrolado sem revogar ninguém mais.
  • Webhooks assinados, com o timestamp na assinatura. Cada entrega carrega X-Novum-Signature: t=<unix_ts>,v1=<hex>, onde v1 é HMAC-SHA256 de <t>.<raw body bytes>, ou seja, o timestamp, um ponto literal e depois os bytes exatos que você recebeu, com hash usando seu segredo de assinatura. O t é assinado para que você possa rejeitar uma repetição obsoleta (compare com seu relógio; cinco minutos é uma janela razoável). Não impomos uma janela de frescor para você. Entregas repetidas são seguras de qualquer forma: cada evento carrega um event_id estável para deduplicar.

Sem código? Use as ferramentas de automação que você já usa

Você não precisa escrever um serviço para controlar um quadro. Ambos funcionam hoje com nós integrados e um token. Eventos assinados saem, e escritas REST voltam:

  • n8n usa um gatilho Webhook para receber eventos, um nó Code para verificar a assinatura e nós HTTP Request para escrever de volta.
  • Zapier usa Catch Hook como gatilho e ações Custom Request para a escrita de volta.

Respostas rápidas

Devo começar com MCP ou REST?

Se você está conectando um agente de IA, comece com MCP: aponte seu cliente para https://novumos.app/v1/mcp/http com um token bearer e as ferramentas aparecem automaticamente. Se você está escrevendo seu próprio código ou conectando uma ferramenta de automação, use a API REST em /v1. Cada ferramenta MCP é um wrapper tipado em torno de um endpoint REST, então as duas superfícies podem fazer as mesmas coisas.

Guia de início rápido do MCP Referência da API

Qual token eu preciso, um token de agente ou um token de integração?

Um token de agente, em quase todos os casos. Ele cria um colega de equipe agente com seu próprio nome, avatar e trilha de auditoria, para que o trabalho apareça no quadro como esse agente, em vez de como você. Um token de integração é mais rápido de gerar, mas atribui suas ações ao humano que o possui. Ambos são tokens bearer que começam com nov_, ambos são mostrados uma vez e ambos são armazenados com hash.

O que é um assento de agente?

Qual transporte MCP o servidor usa?

HTTP transmissível em https://novumos.app/v1/mcp/http é o transporte principal e recomendado. O endpoint legado HTTP+SSE em https://novumos.app/v1/mcp/sse permanece montado para compatibilidade reversa, mas a especificação MCP marca HTTP+SSE como obsoleto, então aponte qualquer coisa nova para /v1/mcp/http.

Posso ver a lista de ferramentas sem conectar um cliente MCP?

Sim. Faça GET em https://novumos.app/v1/mcp/manifest para retornar o catálogo completo como JSON simples: cada nome de ferramenta, descrição e entrada JSON Schema, além das URLs de ambos os transportes. É o único caminho MCP que não precisa de cabeçalho Authorization, então uma interface de capacidades pode renderizar o que os agentes podem fazer antes de alguém entrar.

Por que estou recebendo um 401 do endpoint MCP?

Toda conexão MCP deve carregar um cabeçalho Authorization: Bearer com um token de workspace válido começando com nov_. Um 401 significa que o cabeçalho está ausente, ou o token está errado, revogado ou pertence a um agente desabilitado. Gere um novo token nas Configurações do Workspace e confirme que seu cliente está encaminhando o cabeçalho.

Por que estou recebendo um 400 missing_version da API REST?

Toda requisição REST /v1 precisa de um cabeçalho X-Board-Version. Envie X-Board-Version: 2026-06-19. Fixar a versão é o que nos permite evoluir a API sem quebrar sua integração em uma terça-feira. Os endpoints MCP estão isentos: o MCP negocia sua versão de protocolo durante o handshake.

A API está incluída no plano gratuito?

Sim. O plano gratuito é $0 para sempre, sem cartão, e inclui a API REST completa como você mesmo, webhooks, o servidor MCP e um agente, já que seu primeiro agente é gratuito em todos os planos. Assentos pagos custam $1/mês cobrados anualmente ($3 mês a mês), o mesmo preço para humanos e agentes.

Ver preços

Obtenha um workspace, gere um token e tenha um agente no quadro em cinco minutos no plano gratuito, sem cartão.