MCP tool reference

Eight native LiquidLM tools plus standard search and fetch compatibility aliases.

Native OAuth — default

Configure the remote endpoint in your client and authorize in the browser. This is always the first choice. Cursor editor and CLI share their configuration; the example below uses native OAuth. See your client's guide for its exact setup.

liquidlm mcp install --client cursor
agent mcp login liquidlm

CLI-managed OAuth — second choice

When native OAuth is unsuitable, log in to LiquidLM and configure the client to launch liquidlm mcp serve over stdio. The CLI refreshes the session without requiring a PAT. Initial authorization requires interaction; log in on the machine running the agent. Use CLI 0.1.5 or newer.

  • Cursor, Codex, Claude Code, Claude Desktop and OpenCode have dedicated guides. ChatGPT web and Claude web cannot launch local processes; use remote OAuth.
unset LIQUIDLM_API_TOKEN LIQUIDLM_TOKEN
liquidlm login
liquidlm whoami
# Configure your client to launch this command:
liquidlm mcp serve

PAT — last fallback

Use a static API token only if both OAuth options are unsuitable. Create a PAT limited to the required actions and vaults, then inject LIQUIDLM_API_TOKEN through your secret manager. Keep its value out of configuration files and shell history.

  • LIQUIDLM_TOKEN is an alias. Environment tokens override the saved session: unset both variables to return to OAuth. Remote clients use different environment-reference syntax; follow the client-specific examples.
# LIQUIDLM_API_TOKEN is already injected into this process.
liquidlm mcp serve

Reading, writing and indexing

  • get_knowledge with include_content: true returns UTF-8 file source up to 1 MiB, even before indexing. Notes and links expose their body. Larger and binary files use the download URL.
  • Copy updated_at exactly into put_knowledge.if_match, preserving all fractional digits. knowledge_conflict includes status 409 and current_updated_at: re-read, merge your change and retry. Removing if_match disables conflict protection.
  • Notes and files are stored before asynchronous indexing. Check indexing_status, indexed_at and chunks_stale; search may use previous chunks until the new index completes.
  • Embeddings and entities on get are opt-in through include_embedding and include_entities. Pipeline internals are omitted by default. Inline binary uploads are limited to approximately 12 MiB; use REST presigned uploads for larger files.

Errors and latency

  • needs_auth requires reauthorization. If native OAuth keeps failing, try CLI-managed OAuth before a PAT. Retries cannot restore a revoked session.
  • InvalidToken on download: obtain a fresh URL and preserve it intact. For text, include_content avoids the URL dependency.
  • If a socket closes during a write, read the item before retrying: it may already be stored. Avoid creating duplicate uploads.
  • search_knowledge supports rerank: false and include_pinned: false to reduce optional work. The current Server-Timing header measures authentication only; mcp:tool_completed and mcp:request_completed logs capture tool and total duration. Client elapsed time also includes network and client processing.

Tools

13 tools are exposed over the Model Context Protocol endpoint. Each one maps to a permission-checked action, so a token issued with a read-only grant can call the readers and nothing else.

  • fetch — OpenAI-compatible fetch alias over the scoped LiquidLM knowledge reader. (vault-scoped; needs viewer or above)
  • follow_references — Walk the reference graph outward from an item to the sources it cites or that cite it. (vault-scoped; needs viewer or above)
  • forget_knowledge — Move a knowledge item to the vault's trash so it stops being retrievable. (vault-scoped; needs editor or above)
  • get_document_pages — List or read PDF page children of a document by one-based PDF position. (vault-scoped; needs viewer or above)
  • get_knowledge — Read one knowledge item by id, with its text content and source metadata. (vault-scoped; needs viewer or above)
  • get_related — Find items related to a given one through shared entities and references. (vault-scoped; needs viewer or above)
  • list_entities — List the people, organizations, and concepts extracted from knowledge in scope. (vault-scoped; needs viewer or above)
  • list_knowledge — List knowledge items in scope, filtered by vault, type, and time, without running a search. (vault-scoped; needs viewer or above)
  • pin_knowledge — Mark a knowledge item as the vault's standing context, so agents see it before they search. (vault-scoped; needs editor or above)
  • put_knowledge — Write a note or link into a vault, indexed the same way an upload is. (vault-scoped; needs editor or above)
  • search — OpenAI-compatible search alias over the scoped LiquidLM knowledge search. (vault-scoped; needs viewer or above)
  • search_knowledge — Hybrid semantic and full-text search across the vaults a token can read, returning ranked passages with citations. (vault-scoped; needs viewer or above)
  • unpin_knowledge — Remove a knowledge item from the vault's standing context, leaving the item itself untouched. (vault-scoped; needs editor or above)