Harper MCP Server for HarperDB Resources

Overview

The Harper MCP Server implements the Model Context Protocol (MCP) for HarperDB, exposing HarperDB tables and custom endpoints as structured “Resources” over a JSON-RPC API. It translates HarperDB data into a predictable, discoverable resource surface that other services and tools can consume without needing direct database drivers or custom REST adapters.

This server is useful when you want standardized, read-oriented access to HarperDB from external systems (UIs, integrations, indexing services, or other microservices). It provides a consistent discovery mechanism (resource listing) and read endpoints with support for filtering and pagination, while leveraging HarperDB’s existing authentication and role-based access controls.

Features

• MCP-compatible JSON-RPC endpoint for listing and reading resources
• Exposes HarperDB tables and custom-defined resources as discoverable URIs
• Read-only access to table data and individual rows
• Query/filter support for table reads via URL-style parameters
• Pagination with limit and start parameters
• Predefined static capabilities endpoint (/capabilities.json)
• Standardized JSON-RPC 2.0 error responses
• Integrates with HarperDB authentication (Basic Auth, JWT, mTLS) and role/attribute-level security

Installation / Configuration

Prerequisites:

• Harper platform installed and running (HarperDB v4.5.10 or later).
• Harper stacks configured with the databases/schemas you plan to expose.
• Set the HOST environment variable to the base URL used to construct resource URIs.

Install / deploy to Harper via the Harper Operations API (example):

POST https://harper-server.example:9925
Content-Type: application/json

{
  "operation": "deploy_component",
  "package": "@harperdb/mcp-server@latest"
}

Environment variables (example):

export HOST="https://my-harper.example:9926"
# Other Harper environment settings as required by your deployment

Local development (npm):

npm install @harperdb/mcp-server
# run according to the package's README or container image in Harper

Security & authentication:

• The server relies on HarperDB’s authentication mechanisms. Configure Basic Auth, JWT, or mTLS in Harper to secure requests.
• Harper’s role-based and attribute-level security determines which records/fields each caller can access; the MCP server enforces those Harper-level permissions.

Available Resources

MCP endpoint:

• Single JSON-RPC endpoint: POST /mcp
• Static capabilities: GET /capabilities.json

MCP methods:

Resource URI patterns:

Method	Description	Params	Returns
resources/list	Discover all resources (tables & custom resources)	none	Array of resource metadata (uri, name, description, mimeType)
resources/read	Read contents of a specific resource	{ uri: “”, optional query params }	contents array with item URIs and payloads

Resource type	URI pattern	Example
Table	{HOST}/{table_name}	https://host:9926/Customers
Row	{HOST}/{table_name}/{primary_key}	https://host:9926/Customers/11
Custom resource	{HOST}/{path}/{resource_name}	https://host:9926/api/test

Capabilities endpoint example:

GET /capabilities.json
# returns static JSON describing server and supported interactions

Use Cases

1. Service discovery and integration

   • An external search indexer calls resources/list to find which HarperDB tables to index, then repeatedly calls resources/read for each table to retrieve rows in batches.

   Example request (list):

   { "jsonrpc": "2.0", "id": 1, "method": "resources/list" }
   

2. Read-only API for UIs

   • A dashboard app requests paginated customer records using resources/read for the Customers resource, passing limit and start query parameters to paginate.

   Example read (table):

   {
     "jsonrpc": "2.0",
     "id": 2,
     "method": "resources/read",
     "params": { "uri": "https://host:9926/Customers?limit=25&start=0" }
   }
   

3. Fetch a single row by primary key

   • Integrations that need a specific record can target the row URI directly.

   Example read (row):

   {
     "jsonrpc": "2.0",
     "id": 3,
     "method": "resources/read",
     "params": { "uri": "https://host:9926/Customers/11" }
   }
   

4. Expose custom API endpoints as resources

   • Add Harper custom resources (e.g., aggregated views or RPC-style handlers) and have them appear in resources/list for clients to consume through the same MCP interface.

Error Handling & Notes

• All calls follow JSON-RPC 2.0; errors are returned in the standard JSON-RPC error object with consistent server error codes and messages.
• The MCP server is primarily read-only — it does not provide data mutation methods.
• Ensure the HOST environment variable matches the actual public base URL so resource URIs are valid for clients.

Repository and further reference:

• Source and issues: https://github.com/HarperDB/mcp-server