Servidor MCP

A BriefPanel é um servidor MCP remoto. Conecte-o ao Cursor, ao Claude Code, ao Windsurf ou a qualquer coisa que fale o Model Context Protocol, e seu agente já pode monitorar páginas e ler o que mudou.

Esta é a referência técnica. Para uma visão geral do que a integração resolve, veja a página do MCP.

Endpoint

https://actions.briefpanel.com/mcp

• Transporte — Streamable HTTP, sem estado: uma requisição JSON-RPC por POST, respondida com JSON. Server-Sent Events está descontinuado e não é necessário.
• Versão do protocolo — 2024-11-05, anunciada no handshake initialize.

Um documento de descoberta é publicado em https://briefpanel.com/.well-known/mcp.json, então hosts MCP que descobrem servidores por domínio encontram o nosso sem configuração.

Autenticação

Envie uma chave pessoal de API como token Bearer:

Authorization: Bearer YOUR_BRIEFPANEL_API_KEY

Crie uma chave em Configurações → API e integrações no app (https://app.briefpanel.com/integrations). As chaves começam com bp_mcp_ e a mesma chave vale para a API REST.

Uma chave ausente ou inválida devolve 401 com o cabeçalho WWW-Authenticate.

Escopos

Cada chave carrega escopos. As tools de leitura exigem read; add_source, update_source, pause_source, resume_source e relearn_source exigem write. Chamar uma tool para a qual a chave não tem escopo falha, em vez de não fazer nada silenciosamente.

OAuth

Clientes que precisam de OAuth — conectores personalizados do Claude.ai e do Claude Desktop, conectores do ChatGPT — conseguem conectar sem colar uma chave. Aponte o cliente para o endpoint acima e ele descobre o resto:

• /.well-known/oauth-protected-resource (RFC 9728) e /.well-known/oauth-authorization-server publicam os metadados.
• O cliente se registra sozinho em /oauth/register (RFC 7591), então não há configuração manual de cliente.
• O fluxo é OAuth 2.1 authorization code com PKCE (S256). Você aprova a conexão numa tela de consentimento no app do BriefPanel, logado na conta que está sendo conectada.
• Os escopos são os mesmos read e write que uma chave de API carrega.

Tokens de acesso (bp_oat_) duram uma hora. Refresh tokens duram 30 dias e giram a cada uso.

Os tokens são vinculados ao público (audience) do recurso MCP, então autenticam apenas chamadas MCP. Enviar um para a API REST devolve 401 com uma mensagem dizendo exatamente isso — o token não está quebrado; a REST pede uma chave de API pessoal.

Configuração do cliente

A maioria dos clientes lê o bloco padrão mcpServers:

{
  "mcpServers": {
    "briefpanel": {
      "url": "https://actions.briefpanel.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_BRIEFPANEL_API_KEY" }
    }
  }
}

No Claude Code é um comando só:

claude mcp add --transport http briefpanel https://actions.briefpanel.com/mcp \
  --header "Authorization: Bearer YOUR_BRIEFPANEL_API_KEY"

O Cursor tem um link de instalação em um clique na página do MCP.

Tools

Quatorze tools, nove delas somente de leitura.

Em toda tool paginada, siga pagination.nextCursor enquanto pagination.hasMore for true. Filtros podem deixar uma página vazia ou menor que limit mesmo quando ainda há resultados.

list_sources

Lista as páginas que você monitora, incluindo a configuração de monitoramento e a saúde recente de fetch. Não traz as instruções de monitoramento nem a sensibilidade de uma página — isso é o get_source.

Dois campos dessa resposta são derivados, não guardados, e existem para você nunca receber a promessa de uma verificação que não vem:

get_source

Uma página monitorada por inteiro: tudo o que o list_sources devolve, mais toda configuração que o add_source e o update_source sabem escrever. Leia uma configuração por aqui antes de mudá-la, e chame de novo para confirmar que a mudança entrou.

Além dos campos do list_sources, a resposta traz userPrompt, notificationsEnabled, updateSensitivity e sensitivityLevel. O updateSensitivity vai de 0 a 1 e decide quanto do movimento de uma página vale reportar; o sensitivityLevel nomeia a faixa em que o número cai:

Uma fonte que nunca teve o valor definido reporta o efetivo 0.5 / medium, que é o que as verificações dela realmente usam.

list_source_entries

Os itens que uma página monitorada tem hoje — IDs, títulos, URLs, preços e atributos rastreados — do mais recentemente atualizado para o mais antigo. É por aqui que se chega a um entryId para o get_entry_updates e o get_entry_changes: um item que não mudou há algum tempo não aparece em nenhum feed de mudanças. Uma primeira página vazia quer dizer que a página não tem item algum, o que é uma resposta diferente de "não teve mudanças recentes".

get_source_changes

Atualizações tipadas das entidades nas suas páginas monitoradas. Cada resultado inclui título, URL e tipo da entidade, updateType, importance, o field canônico e valueChange; atualizações de preço também incluem o priceDelta de conveniência. Passe sourceId para ler as mudanças de uma página só, em vez das da conta inteira.

get_entry_updates

O histórico tipado de uma entidade extraída. Tem o mesmo contrato de dados do endpoint REST de atualizações por entidade, inclusive filtros e paginação por cursor.

get_entry_changes

A linha do tempo de fetch/mudança de uma entidade, incluindo se a evidência estruturada de diff está disponível.

get_entry

Um item por inteiro — tudo que list_source_entries retorna para ele mais a prosa que a lista omite: summary (o que a página diz sobre o item — o texto do artigo, a citação, a vaga) e author. Para todo tipo sem preço (citação, notícia, post de blog, vaga) esses dois campos são o conteúdo da entidade. Traz também language, o idioma em que a prosa foi escrita.

get_credit_balance

Seus créditos restantes. Uma verificação gasta um crédito por página que lê — a página da fonte, mais cada página de item que ela seguir. Sem argumentos.

whoami

A identidade e os escopos ligados à chave de API atual — útil para confirmar a que conta uma chave pertence. Sem argumentos.

add_source

Começa a monitorar uma página. Exige o escopo write. Cada verificação depois gasta um crédito por página que ela lê.

Uma página por URL. Uma conta nunca guarda a mesma URL duas vezes. Chamar add_source para uma página que ela já monitora — com qualquer userPrompt — não inicia uma segunda cópia. As configurações da chamada são aplicadas à página que já existe, e só elas: o que você não passar mantém o valor atual.

A resposta diz qual dos dois casos aconteceu:

Mudar o userPrompt assim reaprende como a página é lida, igual ao update_source, pelo mesmo um crédito.

A URL é normalizada antes, então https://www.exemplo.com/a/ e https://exemplo.com/a são a mesma página, não duas.

update_source

Atualiza configurações comuns de uma página monitorada. Exige o escopo write; use pause_source e resume_source para parar e voltar o monitoramento.

Forneça ao menos uma configuração além de sourceId.

Um userPrompt diferente reaprende como a página é lida, o que custa um crédito quando o reaprendizado dá certo. Sem créditos, o prompt é salvo mesmo assim, mas o reaprendizado não roda.

pause_source

Interrompe reversivelmente o monitoramento de uma página. Exige o escopo write; não exclui a fonte nem seu histórico. Volte a monitorar com resume_source ou pelo app do BriefPanel.

resume_source

Volta a monitorar uma página pausada — a contraparte de pause_source. Exige o escopo write.

As verificações voltam na frequência da própria página e passam a gastar créditos de novo, um por página lida. A resposta traz alreadyActive, status e nextFetchTime: retomar uma página que já está sendo monitorada é um no-op relatado como alreadyActive: true, não um erro, e não agenda verificação extra — então repetir a chamada é seguro.

O status é o estado guardado da página, não uma previsão. Numa conta sem créditos o resume ainda devolve active, e o agendador estaciona a página como creditPaused na próxima verificação em que ela vencer — use o get_credit_balance para saber se as verificações vão mesmo acontecer.

Retomar não redefine a base de comparação. A página continua sendo comparada com o estado em que estava quando foi pausada, então a primeira verificação depois de uma pausa longa pode relatar tudo o que mudou no intervalo. Os itens coletados antes da pausa ficam intactos e não são notificados de novo.

relearn_source

Reanalisa como uma página é estruturada, para que as próximas verificações a extraiam com regras recém-aprendidas. Use quando a página foi redesenhada, ou quando os itens dela estão saindo errados. Exige o escopo write e mexe só nas regras de extração — os itens já coletados ficam intactos. Cada chamada custa um crédito quando a reanálise dá certo, e nada quando falha; sem créditos, falha com noCredits e nada roda.

Lendo o histórico

O MCP é feito para conversa: use get_source_changes para um feed entre fontes (ou de uma só, com sourceId), o list_source_entries para chegar a um item, o get_entry para ler a prosa de um item por inteiro e as tools de entidade para o histórico tipado. A API REST expõe quase as mesmas leituras para clientes programáticos, além de recuperar snapshots/blobs e do contrato OpenAPI — mas as configurações do get_source e o filtro sourceId existem só no MCP por ora.