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
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.

Read tools

me

The connected account: identity, plan, onboarding state, teams, and note limits. 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, containers-permissions

tags-list

teams-list, teams-get

instructions-get

files-check_upload, files-get_download_url

Write tools

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

containers-create, containers-update

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.

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 token on /mcp, 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.

Folder-scoped token rejected

API tokens limited to one folder cannot be used with MCP: every call fails with "This API token is scoped to a folder and cannot be used with the MCP server." Use a full-access token (or the OAuth flow), or call the REST API at /api/v1 with the scoped token.

429 Too Many Requests

More than 60 requests in a minute on one token. 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