MCP overview

The Graniite MCP server is what Claude Desktop, Cursor, ChatGPT, n8n's MCP node, and other MCP-aware AI clients connect to. It exposes your library to the agent so it can search, read, and add content inside a conversation.

Endpoint

https://graniite.co/api/mcp

Transport

HTTP, JSON-RPC 2.0. Recent versions of Claude Desktop, Cursor, ChatGPT, and claude.ai speak this natively. Paste the URL into the client's MCP or integrations settings and the client handles the OAuth handshake.

For older clients that only speak stdio MCP, use mcp-remote as a stdio-to-HTTP bridge.

Authentication

The server uses OAuth 2.1 with Dynamic Client Registration when added from a client UI. The client handles the flow on your behalf. You only see the /oauth/authorize consent screen in your browser.

For programmatic use, mint a bearer token at /settings/integrations and pass it as Authorization: Bearer lev_…. See Authentication for the full token and scope model.

Tools

There are four tools: three read and one write.

Update, delete, and organize operations are not exposed via MCP. These operations do not fit agent tool-use loops. Use the REST API for those. See MCP vs REST.

How clients discover the server

The server publishes standard OAuth resource-server metadata at:

https://graniite.co/.well-known/oauth-protected-resource
https://graniite.co/.well-known/oauth-authorization-server

Compliant MCP clients hit these on first connect, register a public OAuth client via DCR (POST /oauth/register), and bounce the user through /oauth/authorize for consent. Every issued token is bound to a folder scope and capability set chosen at consent time.

Scope model

Each token carries:

• Capabilities: read (mandatory) and optionally write.
• Folder scope: either whole-library or a specific list of folders. The add_to_knowledge tool auto-files new items into the token's folder only when the scope is exactly one folder. Multi-folder and whole-library tokens leave new items unfiled. Use REST POST /api/v1/items/:id/folders to file them after.
• kb_only flag: when set, list_recent and get_item skip items flagged as not-in-KB. Search is always KB-only.

See Authentication for how to mint these.

Rate limits

A 429 response includes retry_after_sec. Agents should back off and retry. Clients that ignore the header risk a longer cooldown.