Skip to main content

Model Context Protocol (MCP)

Let your AI agents parse, search, and inspect Knowhere documents by using the Knowhere MCP server.

The Knowhere Model Context Protocol (MCP) server is a thin local stdio wrapper around the Node.js SDK. Agents can start async parse jobs for URLs or local files, list published documents, read outlines and chunks, grep parsed content, and search published documents through retrieval.

Prerequisites​

  • Node.js 20.19+ and npm 10+
  • An MCP host that can run local stdio servers
  • A Knowhere dashboard login or a KNOWHERE_API_KEY

Connect to Knowhere's MCP server​

The MCP package runs as a local stdio server. Log in once, then add the server command to your MCP host.

npx -y @ontos-ai/knowhere-mcp login

The login opens the Knowhere dashboard and stores a local MCP login at ~/.knowhere-node-sdk/mcp/auth.json. During login, choose one of two permissions:

  • Read only: query Knowhere and read existing parsed documents. Parse and delete tools are not exposed.
  • Full access: query, read, start async URL/file parse jobs, cache completed parse jobs, and archive documents.

The host configuration does not need a KNOWHERE_API_KEY when dashboard login is used.

Install in Cursor

To open Cursor and automatically add the Knowhere MCP server, click install. Alternatively, add the following to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "knowhere": {
      "command": "npx",
      "args": ["-y", "@ontos-ai/knowhere-mcp"]
    }
  }
}

Restart Cursor and open its MCP settings to confirm that the Knowhere server is connected.

API-key authentication​

Dashboard login is recommended for local MCP clients because it supports scoped permissions and session revocation. For non-interactive agents, set KNOWHERE_API_KEY before starting the MCP server:

export KNOWHERE_API_KEY="sk_..."
npx -y @ontos-ai/knowhere-mcp

Or pass the key through the host config:

{
  "mcpServers": {
    "knowhere": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ontos-ai/knowhere-mcp"],
      "env": {
        "KNOWHERE_API_KEY": "sk_..."
      }
    }
  }
}

Do not commit API keys to shared MCP configuration files. API-key authentication runs with full access, so provide keys through a secrets manager or local environment variable whenever possible.

Manage MCP sessions​

Use the MCP package commands to inspect or remove the local login:

npx -y @ontos-ai/knowhere-mcp status
npx -y @ontos-ai/knowhere-mcp logout

status shows whether the server is using KNOWHERE_API_KEY or a stored dashboard login, the auth file path, the base URL, and the stored permission.

Set KNOWHERE_BASE_URL when using a non-default Knowhere environment:

export KNOWHERE_BASE_URL="https://staging.knowhereto.ai"
npx -y @ontos-ai/knowhere-mcp login

The default site base URL is https://knowhereto.ai. The MCP package derives API and login routes from this base URL.

Local files and remote agents​

The published MCP package is local stdio MCP. It runs on the same machine as the MCP host process and speaks MCP over standard input and output.

Local file tools read paths from that machine:

  • knowhere_async_parse_file can only read files available to the MCP server process.
  • A file path from a remote chat UI, browser sandbox, or hosted agent is not automatically visible to the local stdio process.
  • For remote or server-side agents, prefer knowhere_async_parse_url for public or signed URLs, or build an upload flow with the Node.js SDK or REST API.

A server-side MCP deployment, if you build one, should still speak MCP over an HTTP transport such as Streamable HTTP. It is not the same thing as calling arbitrary REST endpoints directly.

Building autonomous agents​

MCP tools can read and mutate your Knowhere account depending on the permission you choose. When building autonomous workflows:

  • Prefer read-only permission when the agent only needs document search or inspection.
  • Enable human confirmation for parse and delete tools in your MCP host.
  • Scope API keys to the agent's task and keep them in a vault or local environment variables.
  • Avoid connecting untrusted MCP servers in the same agent session as Knowhere, because prompt injection can cause unsafe tool calls.
  • For large PDFs or OCR-heavy files, use async parse tools and poll status with backoff: 5s, 10s, 20s, 40s, 80s, then cap at 120s.

Tools​

The server exposes the following MCP tools.

ResourceToolAccessDescription
Parseknowhere_async_parse_urlFull accessStart parsing a remote URL and return the job immediately. Poll status with exponential backoff.
Parseknowhere_async_parse_fileFull accessStart parsing a local file path available to the MCP process, upload it if needed, and return the job immediately. Poll status with exponential backoff.
Jobsknowhere_async_get_job_statusRead only, Full accessCheck parse job status and load completed job results into the local cache when available.
Documentsknowhere_list_documentsRead only, Full accessList published Knowhere documents from the remote API, optionally filtered by namespace. Returned documentId values can be passed to outline, read, and grep tools.
Documentsknowhere_delete_documentFull accessArchive, or soft-delete, a published Knowhere document.
Documentsknowhere_get_document_outlineRead only, Full accessReturn the outline for a parsed document by localDocumentId, published documentId, or completed jobId.
Documentsknowhere_read_chunksRead only, Full accessRead exact chunks from a parsed document by page, section path, chunk ID, chunk type, or chunk range. Page screenshots are returned as tagged page assets before preview text.
Documentsknowhere_grep_chunksRead only, Full accessRun literal or regex search over one parsed document. Broad search belongs to knowhere_search.
Retrievalknowhere_searchRead only, Full accessSearch published documents through the Knowhere retrieval API. Page results are marked when a follow-up read call can return readable page asset URLs.

When logged in with Read only permission, the MCP server exposes only knowhere_search, knowhere_list_documents, knowhere_get_document_outline, knowhere_read_chunks, knowhere_grep_chunks, and knowhere_async_get_job_status.

Response contract​

All tools return a single MCP text content item:

{
  "content": [{ "type": "text", "text": "<knowhere operation=\"...\">..." }]
}

The MCP package does not expose structuredContent or tool outputSchema fields. Each response is tagged text rooted at <knowhere operation="...">, using SDK-native camelCase field names such as documentId, jobId, localDocumentId, chunkId, assetUrl, chunkPath, filePath, and storageRoot.

Document tags include storageRoot when the SDK response has document.resultDirectoryPath. Local cache roots are local directory paths. Remote fallback roots use marker values such as remote:<documentId>, and configured parsed-storage roots use marker values such as parsed-storage:<documentId>.

Chunk tags include chunkPath from the source chunk path and a display-only storageLocation when one can be derived. Media and table chunks prefer filePath and include assetUrl when available. Text and page chunks use chunkPath, so marker roots render as logical paths such as parsed-storage:doc_x/chunks/page-1.

For page chunks, <pageAssets primary="true"> appears immediately before <previewText>. Each <pageAsset> carries pageNum, artifactRef, assetUrl, contentType, width, and height when Knowhere provides them. The following <instruction> tells the agent to open or fetch the listed assetUrl before relying on preview text. If a page asset exists without an assetUrl, the response says that the asset is not directly readable.

Search responses mark page results and references with hasPageAssets="true" when the agent should call knowhere_read_chunks next to inspect readable page asset URLs and chunk storage locations.

Async parse responses return the job identifier and source metadata immediately. Use knowhere_async_get_job_status to poll the job until it completes, then pass the returned localDocumentId, documentId, or jobId to outline, read, or grep tools.

See also​