Docs

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-03-26 and 2024-11-05

Capabilities

Tools and prompts

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

These are the current MCP tool names exposed by Hjarni. Use the exact names below.

Read tools

dashboard-get

Counts and recent notes for the personal brain.

search

Unified search across notes, containers, and tags. Supports search_scope, scope, container_id, and tag filters.

notes-list, notes-get

containers-list, containers-get

tags-list

teams-list, teams-get

instructions-get

files-check_upload, files-get_download_url

Write tools

notes-create, notes-update, notes-delete

containers-create, containers-update

tags-create

instructions-update

links-manage

Create or remove bidirectional links between notes.

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

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.
• File tools require a paid Hjarni plan with file uploads enabled.

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-origin requests. Custom clients should avoid unexpected browser origins.

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

Files are a paid-plan feature. If uploads are enabled, prefer files-create_upload_url instead of base64 for anything non-trivial.

Related docs

Use Hjarni with ChatGPT| Use Hjarni with Claude| REST API reference| Privacy, permissions, and AI boundaries

Still stuck?

Email [email protected] and we'll help debug the connection.