# 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](https://hjarni.com/docs/chatgpt) or [Claude setup](https://hjarni.com/docs/claude).

## 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`, `containers-delete`, `containers-restore`

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](https://hjarni.com/docs/email-capture), 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 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

[Use Hjarni with ChatGPT](https://hjarni.com/docs/chatgpt) | [Use Hjarni with Claude](https://hjarni.com/docs/claude) | [REST API reference](https://hjarni.com/docs/api) | [Privacy, permissions, and AI boundaries](https://hjarni.com/docs/privacy-and-permissions) | [What is MCP?](https://hjarni.com/docs/what-is-mcp) | [MCP Config Validator](https://hjarni.com/mcp-config-validator) | [Hjarni vs ChatGPT Projects](https://hjarni.com/compare/hjarni-vs-chatgpt-projects)

Still stuck?

Email [evert@hjarni.com](mailto:evert@hjarni.com) and we'll help debug the connection.