Hjarni

Um segundo cérebro baseado em Markdown com um servidor MCP hospedado. Sua IA lê, pesquisa, cria e vincula suas anotações. Plano gratuito incluído.

Ver em hjarni.com

Documentação

Servidor MCP Hjarni

O Hjarni inclui um servidor MCP integrado para ChatGPT, Claude e outros clientes compatíveis. Use esta página como referência de protocolo e capacidades. Se você só quer conectar um assistente, comece com Configuração do ChatGPT ou Configuração do Claude.

Visão geral

Servidor

second-brain

Endpoint MCP

https://hjarni.com/mcp

Transporte

HTTP Streamable com JSON-RPC 2.0

Versões de protocolo suportadas

2025-11-25, 2025-06-18, 2025-03-26 e 2024-11-05

Capacidades

Ferramentas, prompts e recursos, além da extensão io.modelcontextprotocol/ui (Apps MCP)

Quais clientes devem usar isto

Melhor adequação

  • Conectores personalizados do ChatGPT
  • Claude.ai e Claude iOS
  • Claude Desktop e Claude Code
  • Clientes MCP personalizados que suportam transporte HTTP

Use a API REST em vez disso quando

  • Você está escrevendo sua própria lógica de aplicação
  • Você quer contratos de endpoint explícitos e payloads JSON
  • Você está criando scripts ou automações fora de um cliente MCP

Detalhes do protocolo

POST   /mcp    # JSON-RPC requests
GET    /mcp    # not supported for streaming
DELETE /mcp    # not supported for termination

O servidor responde a métodos MCP padrão, incluindo:

  • initialize
  • tools/list
  • tools/call
  • prompts/list
  • prompts/get
  • resources/list e resources/read: os widgets interativos (ui://), e notas individuais por id (hjarni://notes/42)
  • ping

Autenticação

OAuth

Usado pelos clientes hospedados do ChatGPT e Claude.

  • Fluxo de Código de Autorização com PKCE
  • Descoberta em /.well-known/oauth-authorization-server
  • Metadados de recurso protegido em /.well-known/oauth-protected-resource

Token Bearer

Usado pelo Claude Desktop, Claude Code e clientes personalizados.

{
  "mcpServers": {
    "hjarni": {
      "url": "https://hjarni.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Endpoints OAuth conhecidos

  • GET /.well-known/oauth-authorization-server
  • GET /.well-known/oauth-protected-resource
  • GET /authorize e POST /authorize
  • POST /token
  • POST /register para registro dinâmico de clientes

URIs de redirecionamento pré-aprovadas

  • https://claude.ai/api/mcp/auth_callback
  • https://claude.com/api/mcp/auth_callback
  • https://platform.openai.com/apps-manage/oauth
  • http://localhost:6274/oauth/callback
  • http://localhost:6274/oauth/callback/debug

Outras URIs de redirecionamento devem ser registradas por meio de registro dinâmico de clientes, e URIs de desenvolvimento não locais devem usar HTTPS.

Catálogo de ferramentas

A lista completa de nomes de ferramentas MCP expostos pelo Hjarni. Use os nomes exatos abaixo.

Baixe o catálogo de ferramentas JSON para descrições completas, esquemas de entrada, anotações MCP, tipos de ação e efeitos colaterais.

Ferramentas de leitura

me

A conta conectada: identidade, estado de integração, equipes e limites de notas. Um token de agente obtém apenas sua identidade, as equipes que alcança, suas concessões e as instruções que você escreveu para ele. As instruções do servidor pedem que os clientes chamem isto primeiro em toda conversa.

dashboard-get

Contagens, notas pessoais criadas recentemente e recent_changes: as edições mais recentes em espaços pessoais, de equipe e compartilhados.

search

Busca unificada em notas, contêineres e tags. Suporta search_scope, scope, container_id e filtros de tag. Nota: container_id é ignorado enquanto search_scope é "all" (o padrão), então defina um escopo mais restrito para filtrar por pasta.

notes-list, notes-get, notes-history

containers-list, containers-get

tags-list

teams-list, teams-get

instructions-get

files-check_upload, files-get_download_url

notes-open

Abre uma nota no painel do editor de notas ao lado da conversa, em clientes que mostram apps. Em qualquer outro lugar, retorna os mesmos dados que notes-get.

Ferramentas do painel de notas

notes-panel, notes-search_mentions

Chamadas pelo painel de notas e pelas menções @ do compositor do ChatGPT, não pelo assistente: elas são marcadas como somente-app, então clientes que suportam Apps MCP as mantêm fora da lista de ferramentas do modelo. notes-panel carrega, pré-visualiza e salva a nota aberta com as mesmas permissões que notes-update.

Ferramentas de escrita

notes-create, notes-update, notes-delete, notes-restore, notes-revert

containers-create, containers-update, containers-delete, containers-restore, containers-permissions

containers-permissions define o papel de um colega de equipe em uma pasta de equipe que você administra. Excluir uma pasta move ela e tudo dentro para a Lixeira como uma unidade restaurável; containers-restore traz a unidade inteira de volta, e containers-list com escopo "trashed" mostra o que é restaurável.

tags-create, tags-manage

instructions-update

links-manage

Cria ou remove links bidirecionais entre notas.

files-attach, files-attach_from_url, files-remove, files-create_upload_url

teams-create, teams-invite

Cria uma equipe, ou convida um colega por e-mail (somente proprietário da equipe). Convites enviam um e-mail; um assento é cobrado na aceitação.

email-addresses-list, email-addresses-create

Lista os endereços de captura de e-mail do usuário, ou cria um vinculado a uma pasta (Pro). E-mail enviado para o endereço se torna uma nota lá. Um endereço é uma credencial de escrita, então nunca coloque um em uma nota.

feedback-submit, nudges-dismiss

Envia feedback de produto e dispensa as sugestões no produto que o servidor ocasionalmente apresenta.

Convenções importantes de parâmetros

  • Níveis de instrução são brain, personal_root, container e team.
  • Para busca, use search_scope para distinguir notas pessoais, todas as notas acessíveis ou uma equipe específica.
  • Para links de notas em corpos, a forma robusta é [[id:Note Title]].
  • Para uploads de arquivos, prefira files-create_upload_url em vez de enviar base64 diretamente.

Prompts integrados

O servidor também expõe prompts MCP. Eles são úteis para clientes que suportam descoberta de prompts.

summarize_note

Resuma uma nota e sugira tags e links relacionados. Requer note_id.

weekly_review

Revise a atividade recente e sugira melhorias de organização. days opcional.

research_topic

Sintetize tudo na base de conhecimento relacionado a um tópico. Requer topic.

Permissões e limites comportamentais

  • MCP usa os direitos de acesso da conta Hjarni conectada.
  • Notas de equipe são acessíveis se o usuário pertence à equipe.
  • Contêineres compartilhados são visíveis nos resultados MCP quando o usuário tem acesso.
  • Algumas ações permanecem somente para o proprietário em contêineres pessoais compartilhados.
  • Contas gratuitas podem usar ferramentas de arquivo para até 20 MB em cinco anexos pessoais. Anexos de equipe/compartilhados e capacidade adicional exigem um plano pago.
  • Limites de taxa: 60 solicitações por minuto por conta em /mcp, compartilhados por todos os tokens e sessões da conta, 20 convites de equipe por equipe por hora e 10 registros de clientes OAuth por IP por hora. Exceder um retorna 429.

Solução de problemas

401 Não autorizado

O token é inválido, expirou ou está ausente. Reautorize o cliente OAuth ou gere um novo token em Configurações > Conexões.

403 Origem inválida

O cliente está enviando um cabeçalho Origin não reconhecido. O Hjarni atualmente permite seu próprio host, localhost e origens Claude/Anthropic (claude.ai, claude.com, *.anthropic.com). Clientes personalizados devem evitar origens de navegador inesperadas.

Token de agente recusado

Um token de agente alcança apenas as pastas que recebeu. Uma nota fora delas é lida como não encontrada, uma escrita onde ele tem acesso de leitura falha com "Este token de agente não pode escrever...", e as poucas ferramentas que mudam a conta inteira (criar ou alterar tags, criar equipes, convidar pessoas, compartilhar, captura de e-mail) não são oferecidas a ele. Uma recusa de acesso ou limite nunca é um erro JSON-RPC (uma chamada malformada ainda é). Ela volta como um resultado de ferramenta comum, ou com ok: false e um status (como o limite de notas, ou notes-get em uma nota que ele não pode ler) ou com error: true e texto que começa com Error: (como uma escrita que ele não pode fazer, ou uma pasta que não recebeu). Verifique o resultado para ambos, não apenas que a chamada retornou. Dê mais a ele em Configurações > Conexões, ou use uma conexão de acesso total. Veja Tokens de agente.

429 Muitas solicitações

Mais de 60 solicitações em um minuto em uma conta, contadas em todos os seus tokens e sessões. Recue e tente novamente; a resposta inclui um cabeçalho Retry-After.

Método não encontrado

Use métodos MCP JSON-RPC como tools/list e tools/call. Não trate /mcp como um endpoint REST genérico.

Nenhuma ferramenta aparece após conectar

Certifique-se de que o cliente chamou com sucesso initialize e depois tools/list. Se não, a conexão provavelmente falhou antes do estabelecimento da sessão MCP.

Operações de arquivo falham

Verifique a resposta me para armazenamento de arquivo restante e contagem. Prefira files-create_upload_url em vez de base64 para qualquer coisa não trivial.

Ainda preso?

Envie um e-mail para evert@hjarni.com e ajudaremos a depurar a conexão.

Dê memória à sua IA. Grátis.

Conecte Claude ou ChatGPT a notas que eles podem realmente ler e escrever.

Comece grátis

Dê memória à sua IA. Grátis.