mcp

Harper MCP Server exposes HarperDB data and custom resources via a standardized MCP (Model Context Protocol) API over JSON-RPC. It provides a single /mcp endpoint that accepts MCP methods such as resources/list and resources/read to enumerate available resources and fetch data. Resources include HarperDB tables and any registered custom resources, with support for filtering and pagination when reading table data. The server uses JSON-RPC 2.0 for both requests and responses and serves static capabilities at /capabilities.json. To start using it, ensure HarperDB is running, and that HOST is configured to point to your server base URL; clients will construct URIs from this value when accessing resources.

Prerequisites:

• Node.js (LTS) installed on the machine.
• HarperDB v4.5.10 or later installed and configured.
• Access to HarperDB deployment endpoints as needed by your environment.

Installation steps:

1. Install Node.js from the official site if not already installed.
2. Use the Harper MCP Server via npm/npx: the MCP server is published as an npm package and can be deployed with npx as shown in the repository example.

Example commands:

• Install and run via npx (no global install required): npx -y @harperdb/mcp-server

• Or fetch locally (optional): mkdir -p mcp && cd mcp npm init -y npm i @harperdb/mcp-server node node_modules/@harperdb/mcp-server/dist/server.js

After starting, ensure the server is reachable at the host URL you configure in HOST. Then deploy or interact with MCP endpoints via the /mcp endpoint using JSON-RPC 2.0 requests.

Tips and common considerations:

• Set HOST to the base URL where the MCP server is exposed so that resource URIs are constructed correctly (for example, http://localhost:9925).
• The MCP server provides a predefined capabilities endpoint at /capabilities.json to describe available resources and capabilities.
• Access control is handled via HarperDB authentication mechanisms (Basic Auth, JWT, mTLS). Ensure clients supply appropriate credentials when calling /mcp.
• Use the resources/list method to discover available resources, then resources/read with a URI to fetch data. When reading table data, you can append query parameters to the URI (e.g., ?limit=10&start=20 for pagination and ?name=John for filtering).
• If you modify or extend resources, ensure HarperDB schemas and tables referenced by URIs exist and are accessible by the MCP server’s execution context.