@hugobiotech/kb-mcp

v0.3.4

Published

a month ago

Local KB MCP access with authenticated Streamable HTTP for LightRAG.

0High
0Medium
0Low

Bisheng, LightRAG, and PrimEvo PostgreSQL MCP

Local stdio access for Bisheng Knowledge Base, LightRAG Knowledge Base, and PrimEvo PostgreSQL, plus authenticated Streamable HTTP access for LightRAG through portal-auth.

Streamable HTTP

Start the remote LightRAG transport explicitly with kb-mcp-http. It never falls back to stdio:

LIGHTRAG_BASE_URL=https://ai.hugobiotech.com:27876 \
KB_MCP_HTTP_HOST=127.0.0.1 \
KB_MCP_HTTP_PORT=3000 \
kb-mcp-http

The MCP endpoint is http://127.0.0.1:3000/mcp by default. Remote clients must send their portal-issued LightRAG API key as Authorization: Bearer <token>. The server validates the key and its knowledge-base access before every MCP request, binds each protocol session to its initializing credential, and forwards caller-provided task_id, client_session_id, and trace_id without replacing them with the MCP session ID.

Use a TLS reverse proxy for non-local exposure. The HTTP boundary is controlled explicitly:

KB_MCP_HTTP_HOST, KB_MCP_HTTP_PORT, and KB_MCP_HTTP_PATH configure the listener (defaults: 127.0.0.1, 3000, and /mcp).
KB_MCP_HTTP_ALLOWED_HOSTS is a comma-separated allowlist. It defaults to the listener host. An entry without a port accepts that hostname on any port; an entry with a port requires both. Requests outside the allowlist return 421 before authentication or MCP processing.
KB_MCP_HTTP_ALLOWED_ORIGINS is a comma-separated list of exact HTTP(S) origins. Native clients may omit Origin; when the header is present, the default empty list rejects it with 403.
KB_MCP_HTTP_MAX_REQUEST_BYTES limits each POST body (default 1048576). Oversized bodies return 413; malformed JSON returns 400.
KB_MCP_HTTP_REQUEST_TIMEOUT_MS bounds POST processing (default 30000). A timeout before response headers returns a generic 504. If an MCP SSE response has already started, the server aborts active portal requests and closes the session stream instead. Neither path includes credentials or upstream response content. LIGHTRAG_TIMEOUT_MS separately bounds each portal authorization or tool request (default 30000) and is capped by the HTTP request timeout in HTTP mode.
KB_MCP_HTTP_SESSION_TTL_MS sets the idle session lifetime (default 1800000), and KB_MCP_HTTP_SESSION_CLEANUP_INTERVAL_MS sets the cleanup interval (default 60000). Cleanup leaves active calls alone and closes idle SSE streams when their session expires.
KB_MCP_HTTP_TRUSTED_PROXIES is a comma-separated IP allowlist. Only connections from those addresses may supply the effective X-Forwarded-Host; direct and untrusted connections use Host. Other forwarded headers are ignored.

Missing, malformed, unknown, expired, and credential-mismatched MCP session IDs cannot attach to a session. Session IDs remain transport metadata only. The HTTP process makes upstream requests exclusively through LIGHTRAG_BASE_URL using the portal-auth catalog and /portal-auth/kb-mcp/... gateway routes; do not point it at an individual LightRAG runtime.

Choosing a transport

Use stdio when the client manages a local subprocess and accepts an mcpServers command configuration. This is the compatible default for WorkBuddy, Claude Desktop, Codex Desktop, and existing @hugobiotech/kb-mcp users. The client downloads 0.3.4 through npx, keeps the API key in the subprocess environment, and needs no reachable MCP URL.

Use Streamable HTTP when the client supports a remote MCP URL and bearer-token authentication, or when operators need one centrally deployed adapter. The production URL is https://ai.hugobiotech.com:27876/kb-mcp. Codex CLI supports this form directly:

export LIGHTRAG_API_TOKEN=kbk_live_xxxxxxxxx
codex mcp add lightrag-kb-http \
  --url https://ai.hugobiotech.com:27876/kb-mcp \
  --bearer-token-env-var LIGHTRAG_API_TOKEN

For another Streamable HTTP client, configure the same URL and send Authorization: Bearer <LightRAG API key> on every request. WorkBuddy deployments that expose only command/args/env MCP configuration must use the stdio example below; use the HTTP URL only when that WorkBuddy version explicitly offers Streamable HTTP plus bearer headers. Do not put the URL into a stdio command field.

Both transports expose the same LightRAG tools. Stdio remains local and backward-compatible; HTTP supports protocol sessions, but its Mcp-Session-Id is transport metadata and never replaces task_id, client_session_id, or trace_id.

Production deployment

The kb-mcp-http Compose service has no platform credential. It validates each caller's bearer token through the host nginx gateway at http://ai.hugobiotech.com, mapped to Docker's host gateway so nginx preserves the required server name and /portal-auth route prefix without connecting to a LightRAG runtime. The container joins only the portal Compose network and exposes port 39031 on host loopback for nginx. The public nginx route exposes only /kb-mcp; the Node listener's internal path remains /mcp. Override KB_MCP_HTTP_PORTAL_BASE_URL only when the portal reverse proxy moves to another internal address.

docker compose -f infra/portal-auth/docker-compose.yml up -d --build kb-mcp-http
curl -i http://127.0.0.1:39031/mcp
# Expected: 401 with WWW-Authenticate: Bearer

The Compose defaults set a 1 MiB body limit, a 120 second request deadline, a 90 second portal request timeout, a 30 minute idle session TTL, and a 60 second cleanup interval. Browser origins are denied by default; set KB_MCP_HTTP_ALLOWED_ORIGINS only to exact trusted origins. Change KB_MCP_HTTP_ALLOWED_HOSTS when adding a public hostname. Keep KB_MCP_HTTP_TRUSTED_PROXIES empty unless the listener is placed behind a known proxy whose source IP is stable.

After validating and reloading nginx, monitor the service with:

docker compose -f infra/portal-auth/docker-compose.yml ps kb-mcp-http
docker compose -f infra/portal-auth/docker-compose.yml logs --tail=100 kb-mcp-http
curl -i https://ai.hugobiotech.com:27876/kb-mcp
# Expected without a token: 401, never a portal or runtime route

Run the live transport contract and ScientificEvidence task-grouping check with a temporary verification token in the environment:

LIGHTRAG_API_TOKEN=kbk_live_xxxxxxxxx \
KB_MCP_STDIO_COMMAND=kb-mcp \
KB_MCP_HTTP_URL=https://ai.hugobiotech.com:27876/kb-mcp \
node knowledge-bases/kb-mcp/scripts/live-transport-parity.mjs

The verifier never prints the token. It requires equal tool schemas and catalog results, then checks that each transport's inventory and retrieval child traces carry one explicit task ID and client session ID. For HTTP, it also proves those correlation fields differ from the protocol session ID.

Idle sessions are removed automatically after the configured TTL; an MCP DELETE with the session ID closes a supported session immediately. To roll back HTTP without affecting stdio clients, remove or disable the nginx /kb-mcp location, reload nginx, and stop only kb-mcp-http. Existing npx @hugobiotech/[email protected] subprocess configurations continue unchanged.

Bisheng Configuration

{
  "mcpServers": {
    "bisheng-kb": {
      "command": "npx",
      "args": ["-y", "@hugobiotech/[email protected]"],
      "env": {
        "BISHENG_BASE_URL": "https://ai.hugobiotech.com:27876",
        "BISHENG_API_TOKEN": "bsk_live_xxxxxxxxx"
      }
    }
  }
}

Use a per-user read-only Bisheng KB API token. Do not use a shared company token unless every exposed KB is intentionally company-wide.

LightRAG Configuration

{
  "mcpServers": {
    "lightrag-kb": {
      "command": "npx",
      "args": ["-y", "@hugobiotech/[email protected]"],
      "env": {
        "LIGHTRAG_BASE_URL": "https://ai.hugobiotech.com:27876",
        "LIGHTRAG_API_TOKEN": "kbk_live_xxxxxxxxx",
        "LIGHTRAG_DEFAULT_QUERY_PARAMS": "{\"mode\":\"hybrid\",\"top_k\":12,\"chunk_top_k\":6,\"max_entity_tokens\":6000,\"max_relation_tokens\":8000,\"max_total_tokens\":30000,\"hl_keywords\":[],\"ll_keywords\":[],\"only_need_context\":false,\"enable_rerank\":false,\"include_references\":true,\"include_chunk_content\":true}"
      }
    }
  }
}

Use a per-user LightRAG KB API key created from the central Knowledge Base API Keys page. One token can wrap one or more authorized LightRAG KBs. Use lightrag_kb_list to see the wrapped KBs, then pass kb_id, kb_slug, or exact kb_name in LightRAG tool calls when the token wraps more than one KB.

LIGHTRAG_KB_ID is no longer required. Existing configs may keep it as an optional default KB selector for compatibility, but new desktop examples should omit it and let the token catalog drive selection.

LIGHTRAG_DEFAULT_QUERY_PARAMS is optional. It must be a JSON object encoded as an env string. Supported fields match the LightRAG query tool schema: mode, top_k, chunk_top_k, max_entity_tokens, max_relation_tokens, max_total_tokens, hl_keywords, ll_keywords, only_need_context, enable_rerank, include_references, include_chunk_content, and nested params. The example includes every defaultable top-level field except query, which must come from each tool call. The retired composer-only keys response_type, user_prompt, conversation_history, only_need_prompt, and stream are ignored, so existing client configuration files do not require migration. Unknown keys are ignored. Per-query tool arguments override these defaults.

PrimEvo PostgreSQL Configuration

{
  "mcpServers": {
    "primevo-postgres": {
      "command": "npx",
      "args": ["-y", "@hugobiotech/[email protected]"],
      "env": {
        "PRIMEVO_POSTGRES_BASE_URL": "https://ai.hugobiotech.com:27876",
        "PRIMEVO_POSTGRES_API_TOKEN": "pvpg_live_xxxxxxxxx"
      }
    }
  }
}

Use a per-user PrimEvo PostgreSQL API key created from the central Knowledge Base API Keys page. The desktop config must contain only the public portal base URL and the portal-issued pvpg_live_... token. Do not put PRIMEVO_DATABASE_URL, database passwords, internal service names, or provider credentials in local MCP config.

Tools

bisheng_kb_list: list visible knowledge bases.
bisheng_kb_search: retrieve citation-bearing chunks from selected knowledge bases.
bisheng_kb_fetch_chunk: fetch one chunk returned by search.
lightrag_kb_list: list LightRAG KBs wrapped by the configured token.
lightrag_kb_status: show sanitized status and metadata for a selected LightRAG KB.
lightrag_kb_search: search a selected LightRAG KB.
lightrag_kb_list_tags: list public document tags and facet metadata for a selected LightRAG KB.
lightrag_kb_find_articles: return synced document metadata by tags, exact selectors (pmids, dois, document_ids, document_names, document_identifiers), tag_status=tagged, tag_status=untagged, or tag_status=all; use limit and offset to page complete inventories.
lightrag_kb_search_by_tags: search a selected LightRAG KB and keep only references matching document tags.
lightrag_kb_discover_documents: rank a bounded, reviewable candidate document set from content evidence inside one selected LightRAG KB.
lightrag_kb_accept_document_discovery: freeze reviewed candidates or a bounded top_n policy into an immutable scope snapshot.
primevo_db_schema: list visible PrimEvo PostgreSQL tables and safe metadata.
primevo_db_table: inspect one visible PrimEvo PostgreSQL table.
primevo_db_query: execute one bounded read-only SELECT query through portal-auth.

Advanced query arguments

The two LightRAG query tools (lightrag_kb_search and lightrag_kb_search_by_tags) advertise their supported retrieval arguments directly. The composer-only parameters response_type, user_prompt, conversation_history, only_need_prompt, and stream are retired and ignored when older clients send them. The legacy params wrapper remains accepted for supported retrieval fields.

Environment

BISHENG_BASE_URL: Bisheng server base URL.
BISHENG_API_TOKEN: per-user Bisheng KB API token.
BISHENG_TIMEOUT_MS: optional request timeout, defaults to 30000.
LIGHTRAG_BASE_URL: public AI platform base URL.
LIGHTRAG_API_TOKEN: per-user LightRAG KB API token.
LIGHTRAG_TIMEOUT_MS: optional request timeout, defaults to 30000.
LIGHTRAG_DEFAULT_QUERY_PARAMS: optional JSON object with default LightRAG retrieval parameters.
LIGHTRAG_KB_ID: optional legacy default LightRAG KB corpus id. New configs should omit it.
PRIMEVO_POSTGRES_BASE_URL: public AI platform base URL.
PRIMEVO_POSTGRES_API_TOKEN: per-user PrimEvo PostgreSQL API token.
PRIMEVO_POSTGRES_TIMEOUT_MS: optional request timeout, defaults to 30000.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme