Hubissal MCP server

The Model Context Protocol server for Hubissal exposes your own knowledge base — notes, saved links, uploaded files — plus semantic search to any MCP-capable client. Access is always scoped to the authenticated account: the server reads and writes your content, not anyone else's.

Connection

Endpoint: https://mcp.hubissal.io/mcp
Transport: Streamable HTTP
Protocol version: 2025-03-26
Authentication: Required — OAuth 2.1 + PKCE, or a personal access token
Rate limit: 30 requests per minute

Without a token the endpoint answers 401 Unauthorized. That is the authentication handshake, not an outage.

Authentication

OAuth 2.1 + PKCE · recommended

Browser redirect flow with automatic token refresh. Clients discover the endpoints from the metadata document below — no manual URL wiring.

Personal access token

A static bearer token for clients without OAuth support. Create one in Settings → Connectors; the format is hbs_mcp_<64 hex>.

Connecting a client

Every MCP client needs the same two values: the endpoint URL and, if the client cannot run the OAuth flow, an Authorization header. The exact JSON key names differ per client (Claude Desktop, Cursor, Windsurf, custom agents) — this is the shape most of them use:

{
  "mcpServers": {
    "hubissal": {
      "url": "https://mcp.hubissal.io/mcp",
      "headers": { "Authorization": "Bearer hbs_mcp_…" }
    }
  }
}

Omit headers when the client supports OAuth: it will discover the authorization server from the metadata below.

Scopes

A token carries a subset of these. A tool whose scope is missing answers with a permission error instead of failing silently.

Scope	Grants
notes:read	Read notes
notes:write	Create notes
links:read	Read saved links
links:write	Save links
files:read	Read uploaded files
search:semantic	Vector search over your own content
flavors:read	Read flavor knowledge bases via semantic_search

Tools

11 tools are exposed. This list is the contract: if a tool is not here, it does not exist on the server.

search_notesnotes:read

Keyword search over your notes; returns title and a content preview.

get_notenotes:read

Fetch a single note by id, with its full content.

get_recent_notesnotes:read

The most recently modified notes.

create_notenotes:write

Create a note from a title and Markdown content.

search_linkslinks:read

Keyword search over your saved links.

get_recent_linkslinks:read

The most recently saved links.

check_linklinks:read

Whether a URL is already saved (normalized comparison).

create_linklinks:write

Save a URL; duplicates are detected per user and reported instead of re-created.

search_filesfiles:read

Search your uploaded files by name or description.

get_recent_filesfiles:read

The most recently uploaded files.

semantic_searchsearch:semantic

Vector search across all your content — or across a flavor knowledge base when `flavor_id` is set (that path also needs `flavors:read`).

Machine-readable metadata

These documents are what agents and registries consume. They are the source the page above is derived from.

Troubleshooting

401 Unauthorized: No token, or the token expired. Re-run the OAuth flow or create a new access token.
403 Forbidden: The token lacks the scope the tool needs. Request the scope when authorizing.
429 Too Many Requests: Rate limit: 30 requests per minute per account.
Empty results: Search covers your own content only. A fresh account legitimately returns nothing.