Hjarni

Hjarni MCP server

Hjarni includes a built-in MCP server for ChatGPT, Claude, and other compatible clients. Use this page as the protocol and capability reference. If you just want to connect an assistant, start with ChatGPT setup or Claude setup.

Overview

Server

second-brain

MCP endpoint

https://hjarni.com/mcp

Transport

Streamable HTTP with JSON-RPC 2.0

Supported protocol versions

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

Capabilities

Tools, prompts, and resources, plus the io.modelcontextprotocol/ui extension (MCP Apps)

Which clients should use this

Best fit

• ChatGPT custom connectors
• Claude.ai and Claude iOS
• Claude Desktop and Claude Code
• Custom MCP clients that support HTTP transport

Use the REST API instead when

• You're writing your own application logic
• You want explicit endpoint contracts and JSON payloads
• You are building scripts or automations outside an MCP client

Protocol details

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

The server responds to standard MCP methods including:

• initialize
• tools/list
• tools/call
• prompts/list
• prompts/get
• resources/list and resources/read: the interactive widgets (ui://), and single notes by id (hjarni://notes/42)
• ping

Authentication

OAuth

Used by ChatGPT and Claude's hosted clients.

• Authorization Code flow with PKCE
• Discovery at /.well-known/oauth-authorization-server
• Protected resource metadata at /.well-known/oauth-protected-resource

Bearer token

Used by Claude Desktop, Claude Code, and custom clients.

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

Known OAuth endpoints

• GET /.well-known/oauth-authorization-server
• GET /.well-known/oauth-protected-resource
• GET /authorize and POST /authorize
• POST /token
• POST /register for dynamic client registration

Pre-approved redirect URIs

• 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

Other redirect URIs must be registered through dynamic client registration, and non-local development URIs should use HTTPS.

Tool catalog

The complete list of MCP tool names exposed by Hjarni. Use the exact names below.

Download the JSON tool catalog for complete descriptions, input schemas, MCP annotations, action types, and side effects.

Read tools

me

The connected account: identity, onboarding state, teams, and note limits. An agent token gets only its identity, the teams it reaches, its grants and the instructions you wrote for it. The server's instructions ask clients to call this first in every conversation.

dashboard-get

Counts, recently created personal notes, and recent_changes: the latest edits across personal, team, and shared spaces.

search

Unified search across notes, containers, and tags. Supports search_scope, scope, container_id, and tag filters. Note: container_id is ignored while search_scope is "all" (the default), so set a narrower scope to filter by folder.

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

Opens a note in the note editor panel beside the conversation, in clients that show apps. Everywhere else it returns the same data as notes-get.

Note panel tools

notes-panel, notes-search_mentions

Called by the note panel and by ChatGPT's composer @-mentions, not by the assistant: they are marked app-only, so clients that support MCP Apps keep them out of the model's tool list. notes-panel loads, previews and saves the open note with the same permissions as notes-update.

Write tools

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

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

containers-permissions sets a teammate's role on a team folder you administer. Deleting a folder moves it and everything inside to the Trash as one restorable unit; containers-restore brings the whole unit back, and containers-list with scope "trashed" shows what is restorable.

tags-create, tags-manage

instructions-update

links-manage

Create or remove bidirectional links between notes.

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

teams-create, teams-invite

Create a team, or invite a teammate by email (team owner only). Invites send an email; a seat is billed on accept.

email-addresses-list, email-addresses-create

List the user's email capture addresses, or create one bound to a folder (Pro). Mail sent to the address becomes a note there. An address is a write credential, so never put one in a note.

feedback-submit, nudges-dismiss

Send product feedback, and dismiss the in-product suggestions the server occasionally surfaces.

Important parameter conventions

• Instruction levels are brain, personal_root, container, and team.
• For search, use search_scope to distinguish personal notes, all accessible notes, or a specific team.
• For note links in bodies, the robust form is [[id:Note Title]].
• For file uploads, prefer files-create_upload_url over sending base64 directly.

Built-in prompts

The server also exposes MCP prompts. These are useful for clients that support prompt discovery.

summarize_note

Summarize a note and suggest tags and related links. Requires note_id.

weekly_review

Review recent activity and suggest organization improvements. Optional days.

research_topic

Synthesize everything in the knowledge base related to a topic. Requires topic.

Permissions and behavioral limits

• MCP uses the access rights of the connected Hjarni account.
• Team notes are accessible if the user belongs to the team.
• Shared containers are visible in MCP results when the user has access.
• Some actions remain owner-only for shared personal containers.
• Free accounts can use file tools for up to 20 MB across five personal attachments. Team/shared attachments and additional capacity require a paid plan.
• Rate limits: 60 requests per minute per account on /mcp, shared by all of the account's tokens and sessions, 20 team invites per team per hour, and 10 OAuth client registrations per IP per hour. Exceeding one returns 429.

Troubleshooting

401 Unauthorized

The token is invalid, expired, or missing. Re-authorize the OAuth client or generate a new token in Settings > Connections.

403 Invalid origin

The client is sending an unrecognized Origin header. Hjarni currently allows its own host, localhost, and Claude/Anthropic origins (claude.ai, claude.com, *.anthropic.com). Custom clients should avoid unexpected browser origins.

Agent token refused

An agent token reaches only the folders it was given. A note outside them reads as not found, a write where it has read access fails with "This agent token can't write...", and the few tools that change the whole account (creating or changing tags, creating teams, inviting people, sharing, email capture) are not offered to it. A refusal for access or a limit is never a JSON-RPC error (a malformed call still is). It comes back as an ordinary tool result, either with ok: false and a status (such as the note limit, or notes-get on a note it cannot read) or with error: true and text that starts with Error: (such as a write it may not make, or a folder it was not given). Check the result for both, not just that the call returned. Give it more in Settings > Connections, or use a full-access connection. See Agent tokens.

429 Too Many Requests

More than 60 requests in a minute on one account, counted across all of its tokens and sessions. Back off and retry; the response includes a Retry-After header.

Method not found

Use MCP JSON-RPC methods like tools/list and tools/call. Do not treat /mcp as a generic REST endpoint.

No tools appear after connecting

Make sure the client successfully called initialize and then tools/list. If not, the connection likely failed before the MCP session was established.

File operations fail

Check the me response for remaining file storage and count. Prefer files-create_upload_url instead of base64 for anything non-trivial.

Still stuck?

Email evert@hjarni.com and we'll help debug the connection.

Give your AI a memory. Free.

Connect Claude or ChatGPT to notes they can actually read and write.

Get started free

Give your AI a memory. Free.