harborrag-mcp-server

Owns the FastMCP transport, pre-execution policy, and durable audit boundary.

Folder ownership

__main__.py                 stdio / HTTP launcher and flag parsing
server/base.py              server protocol
server/server.py            tool registry, policy enforcement, dispatch
server/http.py              loopback Streamable HTTP transport and status UI
server/http_auth.py         owner-only bearer and tenant authorization
server/static/status.html   status page and Tool Playground
server/explorer/            HarborRAG Explorer MCP App served by harborrag-mcp-ui
configuration/              config/mcp.yaml loading, validation, env overrides
policy.py                   compiled safety ceilings
audit.py                    JSONL audit writer
defaults/mcp.yaml           packaged fallback configuration

The 11 reader tool implementations, schemas, catalog, and checked dispatcher live in harborrag_engine.tools. Generic contracts live in harborrag_core. harborrag_runtime.composition.readers connects the reader backends and owns their lifecycle. MCP adapts authentication, registration, configuration, and protocol responses; the optional agent uses the same dispatcher.

Team deliverables

• The shipped transport exposes the eleven read-only tools documented in MCP Tools: evidence search/fetch/context, source discovery, static graph description, bounded triplet/subgraph/path traversal, exact graph-node resolution, document inventory, and faceted entity ranking. Chat and agent are not MCP tools; they are served only through the HarborRAG REST API's /v1/chat/completions and /v1/agent/completions endpoints.
• Every attempt and outcome is durably audited with a principal identifier and arguments digest; raw arguments and tokens are never recorded.
• Shared reader execution outcomes are recorded separately by the runtime at ~/.harborrag/tool-execution-audit.jsonl; set HARBORRAG_TOOL_EXECUTION_AUDIT_PATH to choose another path. The invocation identifier correlates execution records with MCP transport records.
• Declared input schemas plus argument, result-count, and serialized-output budgets are enforced.
• Ingestion-capability tools fail closed until explicitly enabled.
• Transport creation fails closed without authentication unless the caller explicitly selects local unauthenticated stdio.
• Service-level tools must never expose raw database/provider access or place retrieved document text in descriptions.

Install the reader profile before running the launcher. Reader serving connects the configured database, object store, vector store, graph store, and embedding client. It does not start conversation memory, chat, an agent, or an ingestion executor, and it does not provision object-store buckets:

uv sync --package harborrag-mcp-server --extra reader

Run the standard stdio transport from a checkout:

scripts/deployment/mcp.sh

Build the equivalent non-root container and verify its advertised registry:

docker build -f deploy/docker/Dockerfile.mcp -t harborrag-mcp .
docker run --rm harborrag-mcp --check

For a real stdio MCP session, run the image with an attached stdin, the database/model environment files, and connectivity to the configured data services. The image entrypoint is python -m harborrag_mcp_server, so MCP arguments such as --check or --transport http are forwarded directly.

harborrag-mcp is the canonical installed command. It accepts --env-file for deployment settings; the checkout script only selects Python and passes --local-stack-root to translate local database/model/MCP env files. Neither path loads API settings or executes env files as shell code. The command constructs the reader application and communicates over stdin/stdout. It is a child process launched by an MCP client, not an interactive terminal or HTTP service. Run scripts/deployment/mcp.sh --check yourself to perform a real MCP handshake and print the eleven advertised tool names without connecting to providers.

Run an authenticated local Streamable HTTP endpoint and status page:

scripts/deployment/dev.sh bootstrap
scripts/deployment/dev.sh up         # data services + API, which applies the migrations
scripts/deployment/mcp.sh --http

The browser status page is http://127.0.0.1:8010/, health is available at http://127.0.0.1:8010/healthz, and MCP clients connect to http://127.0.0.1:8010/mcp with the token in an Authorization: Bearer header. Override the loopback host, port, or path with --host, --port, and --path; this local static-token mode intentionally rejects non-loopback hosts. The bootstrap command generates the token in the Git-ignored env/.env.mcp file with mode 0600; override that path with MCP_ENV_FILE.

Tool Playground

Open the browser page, enter the bearer token, provide a tenant ID, and select Load tools. The page builds an argument form from the effective JSON schema and executes the selected tool with Run tool. Tenant-specific enablement, defaults and limits are applied before execution, and each attempt is audited.

Chat and agent are not part of this catalog; use the HarborRAG REST API's /v1/chat/completions and /v1/agent/completions endpoints instead.

The owner-only browser API is:

• GET /api/tools?tenant_id=<tenant> for the effective catalog;
• POST /api/tools/call with {"name": "...", "arguments": {...}} to run a tool.

The API is a local administrative convenience, not a second unprotected tool transport. It requires the same owner bearer token as configuration editing.

Explorer MCP UI server

harborrag-mcp-ui is an optional second MCP server that serves only the HarborRAG Explorer, a FastMCP 4 FastMCPApp whose Prefab UI helps people search the corpus. Hosts that support MCP Apps render it, including the MCP Inspector's Apps tab. The reader server works without it: its catalog is unchanged, it never imports server/explorer/, and FastMCP Apps and Prefab come only from the ui extra (harborrag-mcp-server[ui]).

In a checkout, scripts/deployment/mcp-ui.sh runs it in Docker from deploy/compose/docker-compose.mcp-ui.yml and deploy/docker/Dockerfile.mcp-ui, a thin layer over the reader image.

• open_explorer is the model-visible entry point and returns the UI.
• explorer_search, explorer_read, explorer_browse and explorer_graph are app-only backends for search, reading, browsing and graph tracing. They call the registered reader handlers, so authentication, tenant binding, configuration, budgets and audit are shared.
• Found evidence goes back to the conversation only when the user selects Send to chat or Add to conversation context.
• It takes the reader server's flags and environment, listens on HARBORRAG_MCP_UI_PORT (default 8011) over HTTP, and serves /healthz only.
• The renderer loads from cdn.jsdelivr.net, declared in the resource CSP.

See Setup and Integration for running it and for the MCP Inspector workflow.

Tool configuration

The versioned configuration lives at config/mcp.yaml by default. Set HARBORRAG_MCP_CONFIG_PATH or pass --config after --http to select another file. The configuration controls:

• global policy budgets;
• globally enabled tools;
• optional argument defaults and numeric upper limits;
• per-tenant enabled state, defaults, and limits.

Required fields and tenant_id can never receive defaults, unknown tools and fields are rejected, and configured limits cannot exceed each tool's compiled safety ceiling. Tenant IDs are canonicalized before policy lookup and execution, and configuration tenant keys may not contain surrounding whitespace. These environment variables override the file without being persisted back into it:

• HARBORRAG_MCP_MAX_RESULTS
• HARBORRAG_MCP_MAX_ARGUMENT_BYTES
• HARBORRAG_MCP_MAX_OUTPUT_BYTES
• HARBORRAG_MCP_DISABLED_TOOLS (comma-separated tool names)

In HTTP mode, enter the bearer token in the status page and use Load, Save, or Reload YAML. The owner-only API is GET/PUT /api/config and POST /api/config/reload. Saves use revision checks and atomic replacement; audit records contain only revision hashes, never configuration values.

Defaults, limits, budgets, and tenant overrides are enforced immediately. Changes to global advertised tool schemas or enabled tools set restart_required=true; restart the MCP process so connected clients receive the new advertised catalog.

Network transports must be constructed with a FastMCP authentication provider. MCP tool calls require an authenticated token carrying role=owner and an explicit tenants claim containing the requested tenant. Global owners must carry the deliberate wildcard claim tenants=["*"]. The explicit local override is for stdio only and opens no listener.

Package tests

Tests for this package live in:

packages/harborrag-mcp-server/tests/

Run from the repository root:

pytest packages/harborrag-mcp-server/tests

Keep new tests in this folder when adding or changing behavior owned by this package.