Documentation

Connect your AI to your brain.

Hjarni has a built-in MCP server. Claude and ChatGPT can read, search, and organize your notes directly. Here's how to set it up.

Three ways to connect.

A

Claude.ai or Claude iOS

Recommended

Claude handles authentication automatically. No tokens to manage.

  1. Open Settings in Claude and find Integrations.
  2. Add a new integration with the URL: https://hjarni.com/mcp
  3. Log in to Hjarni when redirected.
  4. Done. Ask Claude about your notes.
B

ChatGPT

ChatGPT supports MCP servers in Plus, Pro, and Team plans.

  1. Open Settings > Connected apps in ChatGPT.
  2. Tap Add MCP server.
  3. Enter the URL: https://hjarni.com/mcp
  4. Log in to Hjarni when redirected.
  5. Done. Ask ChatGPT about your notes.
C

Claude Desktop, Claude Code, or other MCP clients

For any client that supports Streamable HTTP transport.

  1. Go to Settings > Connections in Hjarni.
  2. Generate an API token and copy it.
  3. Add this to your client config:
{
  "mcpServers": {
    "hjarni": {
      "url": "https://hjarni.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Restart your client after saving.

Protocol details.

Protocol
MCP 2025-03-26 (also supports 2024-11-05)
Transport
Streamable HTTP (JSON-RPC 2.0)
Endpoint
POST https://hjarni.com/mcp
Authentication
Bearer token via Authorization header
OAuth discovery
GET /.well-known/oauth-authorization-server

Read tools.

Browse and search your brain. Nothing is modified.

get_dashboard

Overview of your brain — note, container, and tag counts, inbox size, recent notes.

search

Search across notes, containers, and tags. Filter by type, container, tags, or scope. Requires query

list_notes

All your notes, paginated. Filter by container, tags, scope (active, archived, inbox, favorited), or sort order.

get_note

Full note with body, tags, container, linked notes, and file attachments. Requires id

list_containers

List folders. Root-level by default, or all at once.

get_container

Container details with optional tree view (ancestors and children). Requires id

list_tags

All tags with note counts.

list_teams

Teams you belong to.

get_team

Team details with recent notes. Requires id

get_instructions

Your conventions and rules for how your AI should use your brain. Set at four levels: brain, personal, container, or team. Requires level

check_file_upload

Check if a file upload link has been used (pending, completed, or expired). Requires token

get_file_download_url

Temporary download URL for a file attachment. Requires note_id, file_id

Write tools.

Create, update, and delete. Your AI confirms before making changes.

create_note

New note with Markdown body, wiki-links, tags, summary, and source URL. Place in a container or team. Requires title

update_note

Change content, tags, container, or status (archive, favorite). Requires id

delete_note

Permanently delete a note. Requires id

create_container

New folder, optionally nested under a parent. Requires name

update_container

Rename, move, or update the description of a folder. Requires id

create_tag

New tag. Requires name

manage_note_links

Link or unlink two notes bidirectionally. Requires action, source_note_id, target_note_id

update_instructions

Set rules for how your AI uses a specific area of your brain. Requires level, instructions

add_file_to_note

Attach a file via base64. Requires id, filename, data

add_file_to_note_from_url

Fetch a file from a URL and attach it. Requires id, url

remove_file_from_note

Remove a file attachment. Requires note_id, file_id

create_file_upload_url

One-time upload link. The user uploads directly from their browser. Requires note_id

OAuth for developers.

Building a custom MCP client? Hjarni supports OAuth 2.0 Authorization Code with PKCE.

  1. Discover endpoints: GET /.well-known/oauth-authorization-server
  2. Register your client (optional): POST /register with client_name and redirect_uris
  3. Redirect the user to GET /authorize with:
    • response_type=code
    • client_id, redirect_uri, state
    • code_challenge + code_challenge_method=S256
  4. User logs in on Hjarni, gets redirected back with code and state.
  5. Exchange code for token: POST /token with grant_type=authorization_code, code, code_verifier.
  6. Use the token as Bearer in the Authorization header for POST /mcp.

Pre-approved redirect URIs

  • https://claude.ai/api/mcp/auth_callback
  • https://claude.com/api/mcp/auth_callback
  • http://localhost:6274/oauth/callback (development)

Other URIs must be registered via POST /register. HTTPS required except localhost.

Something not working?

401 Unauthorized

Token is invalid or expired. Generate a new one in Settings > Connections. For OAuth, re-authorize through your MCP client.

403 Invalid origin

Your client is sending an Origin header we don't recognize. Only recognized MCP clients (Claude, ChatGPT), localhost, and the Hjarni domain are allowed.

Connection timeout

Check the URL is exactly https://hjarni.com/mcp — no trailing slash. Your client must support Streamable HTTP transport. Stdio won't work.

OAuth redirect fails

The redirect_uri must match a pre-approved URI exactly, or be registered via dynamic client registration.

Method not found

Use POST /mcp. GET and DELETE are not supported for tool calls.

Tools not appearing

Your client should call tools/list after connecting. If nothing shows up, authentication likely failed — check that initialize returns a valid response.

File attachment errors

File attachments require a Pro plan. Upgrade in Settings.

Still stuck?

Email [email protected] and we'll sort it out.