Browse documentation

Hjarni MCP server

Hjarni runs an official hosted MCP server for ChatGPT, Claude, and other compatible clients. You do not need to install or maintain a local MCP server. 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
Note access: ChatGPT and Claude can search, read, create, and update the same saved Markdown notes, within the connection's permissions. The tool catalog lists the available actions.
Hjarni plan: Free includes MCP access and 25 personal notes. Features such as email capture and higher note or attachment limits require a paid plan; see plans and limits. Your assistant's subscription and connector requirements are separate.
Transport: Streamable HTTP with JSON-RPC 2.0
Supported protocol versions: 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05 through initialize, plus 2026-07-28 through server/discover
Capabilities: Tools, prompts, resources, and events, plus the io.modelcontextprotocol/ui extension (MCP Apps)

Connect ChatGPT and Claude

ChatGPT

Open Hjarni in the ChatGPT Apps Directory, click Connect, then sign in to Hjarni and authorize access. This path does not require developer mode or a manually entered server URL.

Follow ChatGPT setup for current plan requirements and a save, find, and update check.

Claude

Open Hjarni notes in the Claude Connectors Directory for Claude.ai, iOS, or Desktop, then connect and sign in. Claude Code adds the hosted server from the CLI and uses OAuth too.

Follow Claude setup for the command, current plan requirements, workspace admin requirements, and a save, find, and update check.

OAuth connections reach the notes your Hjarni account can access, unless you limit one on the sign-in screen to some folders, to reading only, or both. For a client that takes a token instead, use an agent token with explicit read or write grants. See privacy and permissions for the boundaries, and note history to compare saved edits and restore an earlier body.

Other MCP clients need Streamable HTTP transport and a supported authentication method. For scripts or applications that need explicit HTTP endpoints instead of MCP, use the REST API reference.

Try one client brief in ChatGPT and Claude

Connect both assistants to the same Hjarni account using the guides above. Start with the Client Project Context template, which creates a project index and a blank brief. Keep one brief per client and project.

Save in ChatGPT. Ask it to fill the brief with confirmed scope, preferences, dated decisions and the next action.
Update in Claude. Ask it to retrieve the full brief and its source link. Draft changes in chat, then confirm saving them to the same note.
Check in a fresh ChatGPT chat. Retrieve the brief again and check the updated status and next action.

The recorded client-context walkthrough shows this workflow with a fictional client brief. Explicitly request retrieval in each chat; connection does not guarantee recall or synchronize conversations or native assistant memories.

Review and recover. Use note history to compare saved note bodies and restore an earlier whole body as a new version. Restoring replaces later body edits; the current title, folder and other fields stay unchanged. History reviews saved changes; approval before a write depends on your host and connection settings.
Keep a copy. Inspect the sample Markdown export of active notes and attachments. Export happens in Hjarni, not through an MCP tool. Check what gets exported: the standard ZIP excludes archived and trashed notes, revision history and folder instructions.

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: the interactive widgets (ui://)
resources/read: those widgets, and single notes by id (hjarni://notes/42)
events/list, events/subscribe and events/unsubscribe (see Events)
server/discover: for 2026-07-28 clients, the supported versions, capabilities and instructions in one call
ping

Authentication

OAuth

Recommended for ChatGPT and Claude, including Claude Desktop and Claude Code. The client handles sign-in; no manually copied API token is needed.

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

Bearer token

For custom clients that send an API token in the Authorization header. Create a full-access token or a restricted agent token in Settings > Connections; configure only the access the client needs.

{
  "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. Not offered to agent tokens.

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

files-attach, files-attach_from_url and files-remove work on personal notes only. Team and shared notes attach through files-create_upload_url.

teams-create, teams-invite

Create a team, or bring a teammate in (team owner only). teams-invite with an email sends an invite; without one it returns a shareable join link, or revokes it with action: "revoke". On a subscribed team, each person who joins adds a billed seat.

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.

Events

A connection can subscribe to changes in the notes it can read, and Hjarni POSTs each change to a callback URL. These are protocol methods, not tools: the client calls events/list, events/subscribe and events/unsubscribe, and a refusal comes back as a JSON-RPC error. The server advertises the events capability on initialize and server/discover. Delivery is by webhook only; events/poll and events/stream are not supported.

note.created

A note was created. Filters: container_id (that folder and the folders inside it) and team_id.

note.updated

A note's title, body or summary changed, or it moved to another folder. Several edits in quick succession arrive as one event. Filters: container_id, team_id and note_id.

note.deleted

A note was moved to the Trash. Filters: container_id, team_id and note_id.

Each event carries note_id, title, container_id, team_id and changed_by (this_connection, you or someone_else). Read the note itself with notes-get.
The callback must be an https URL that answers a one-time verification challenge, and the subscription needs a whsec_ signing secret. Deliveries are signed the Standard Webhooks way.
Access is checked when you subscribe and again before every delivery, so an agent token only hears about the folders it was given. Each connection can hold up to 25 live subscriptions.
ChatGPT uses events for event-triggered tasks in Work chats, over protocol 2026-07-28. See Turn new Hjarni notes into automatic AI workflows.

Permissions and behavioral limits

OAuth uses the connected account's permissions by default. At sign-in or in Settings > Connections, you can limit each assistant to selected folders, read-only access, or both. See the folder-access walkthrough. Agent tokens provide the same folder and read/write controls for compatible token clients. Neither can gain more access than the account has.
Team notes require both the user's team access and the connection's access to those notes.
Shared containers appear in MCP results only where both the user and the connection have 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, and 10 OAuth client registrations per IP per hour. Exceeding either returns 429. teams-invite also sends at most 20 email invites per team per hour; past that the tool returns an error result, not a 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 act on the whole account (creating or changing tags, creating teams, inviting people, sharing, email capture, dismissing suggestions, and the note panel's notes-open, notes-panel and notes-search_mentions) 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.

Related docs

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.

Get started free

Your notes on every device

Hjarni has its own native apps. Free on every plan for iPhone, iPad and Mac and Android. Same account, same notes as the web. An internet connection is required.