Harper MCP Server

What is Harper MCP Server about?

The server implements the Model Context Protocol (MCP) API for HarperDB, allowing clients to list available resources (tables and custom endpoints) and read their contents via a single /mcp JSON‑RPC endpoint.

How to use Harper MCP Server?

Deploy the component to a Harper instance using the Operations API (or install locally via npm).
```
{
  "operation": "deploy_component",
  "package": "@harperdb/mcp-server@1.0.0"
}
```
Set the HOST environment variable to the base URL of the server (e.g., http://localhost:9925).
Send JSON‑RPC requests to POST /mcp:
- List resources: { "jsonrpc": "2.0", "id": 1, "method": "resources/list" }
- Read a resource: { "jsonrpc": "2.0", "id": 2, "method": "resources/read", "params": { "uri": "http://localhost:9925/Customers" } }
Apply optional query parameters (?attribute=value&limit=10&start=20) to filter or paginate table results.

Key features of Harper MCP Server

MCP‑compatible JSON‑RPC 2.0 API with a single endpoint (/mcp).
Static /capabilities.json describing server capabilities.
Read‑only access to HarperDB tables and custom resources.
Built‑in filtering (attribute=value) and pagination (limit, start).
Standardized error responses following JSON‑RPC error codes.
Leverages Harper’s role‑based, attribute‑level security (Basic Auth, JWT, mTLS).

Use cases of Harper MCP Server

Data aggregation services that need a uniform way to pull structured data from multiple HarperDB tables.
Micro‑frontend applications requiring read‑only access to backend resources without exposing full database credentials.
Integration bridges connecting HarperDB with external systems that understand MCP/JSON‑RPC.
Reporting tools that can list resources dynamically and fetch paginated data for dashboards.

FAQ from the Harper MCP Server

Q: Do I need a specific HarperDB version? A: Yes, version 4.5.10 or later is required.

Q: How is authentication handled? A: The server relies on HarperDB’s built‑in authentication (Basic Auth, JWT, or mTLS). No separate auth mechanism is required.

Q: Can I modify data through this server? A: The server currently provides read‑only access; write operations are not exposed via MCP.

Q: Where can I find the list of supported methods? A: resources/list and resources/read are the two MCP methods implemented.

Q: How are errors returned? A: Errors follow the JSON‑RPC 2.0 spec with codes such as -32601 (Method not found), -32602 (Invalid params), and -32603 (Internal server error).

A server implementation of the Model Context Protocol (MCP), designed to expose data in HarperDB as structured "Resources" accessible via standardized JSON-RPC calls.

Note: Requires HarperDB version 4.5.10 or later.

What is Harper

Harper is a Composable Application Platform that merges database, cache, app logic, and messaging into a single runtime. Components like this plug directly into Harper, letting you build and scale distributed services fast, without managing separate systems. Built for geo-distributed apps with low latency and high uptime by default.

Features

MCP-compatible API server for Harper
Predefined static capabilities endpoint (/capabilities.json)
Provides read-only access to data from Harper tables and custom resources
Supports filtering data in Harper tables using query parameters
Handles pagination (limit, start) for table data retrieval
Provides standardized error responses

Getting Started

Prerequisites

Harper stack installed globally.
Ensure HarperDB v4.5.10 or later is configured and running with necessary databases and schemas.
Environment variable HOST should be set to the base URL of your server. This is used to construct resource URIs.

Deploying to Harper

The Harper mcp-server is published to NPM and can be installed using Harper's Operation API.

i.e.

POST https://harper-server.com:9925

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

Security & Authentication

Harper employs role-based, attribute-level security to ensure users access only authorized data. Requests to the server are authenticated using HarperDB's built-in authentication mechanisms, which include Basic Auth, JWT, and mTLS. See Harper Security Docs for more details.

API

MCP Methods

The server implements the following MCP methods:

resources/list: Lists all available resources (HarperDB tables and custom resources).
resources/read: Retrieves data for a specific resource based on its URI.

A single endpoint, /mcp handles all requests. The server uses JSON-RPC 2.0 for communication.

Request Format: All requests are sent as JSON-RPC 2.0 formatted JSON objects.
Response Format: The server responds with JSON-RPC 2.0 formatted JSON objects.
Error Handling: The server returns standardized error responses.

Resource URIs

Tables: Resources representing HarperDB tables are accessed via URIs like:
```
{HOST}/{table_name}
```
- Example: http://localhost:9925/my_table
Table Rows: Individual rows within a table can be accessed using the primary key:
```
{HOST}/{table_name}/{primary_key_value}
```
- Example: http://localhost:9925/my_table/123 (where 123 is the primary key value)
Custom Resources: Custom resources are accessed via URIs defined by their registered path:
```
{HOST}/{path}/{resource_name}
```
- Example: http://localhost:9925/custom/my_resource

Usage

1. Listing Resources

POST /mcp

Sample Request:

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

Sample Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"resources": [
			{
				"uri": "http://localhost:9926/CustomerOrders",
				"name": "CustomerOrders",
				"description": "CustomerOrders table with attributes: id (PK - Int), customerId (string), customer (Relationship from customerId - Customers), itemSku (String), item (Relationship from itemSku - Items), subTotal (Float), orderTotal (Float), date (DateTime). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/Customers",
				"name": "Customers",
				"description": "Customers table with attributes: id (PK - Int), email (String), phoneNumber (String), customerName (String), country (String), orders (Relationship to customerId - array). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/Items",
				"name": "Items",
				"description": "Items table with attributes: sku (PK - String), itemName (String), itemDescription (String), unitPrice (Int). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/TestCustomer",
				"name": "TestCustomer",
				"description": "Customers table with attributes: id (PK - Int), email (String), phoneNumber (String), customerName (String), country (String), orders (Relationship to customerId - array). Results can be filtered with optional query parameters.",
				"mimeType": "application/json"
			},
			{
				"uri": "http://localhost:9926/api/test",
				"name": "test",
				"description": "REST Resource.",
				"mimeType": "application/json"
			}
		]
	}
}

2. Get resources data

POST /mcp

Sample Request:

{
	"jsonrpc": "2.0",
	"id": 2,
	"method": "resources/read",
	"params": {
		"uri": "http://localhost:9926/Customers"
	}
}

Sample Response:

{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"contents": [
			{
				"uri": "http://localhost:9926/Customers/11",
				"mimeType": "application/json",
				"text": "{\"id\":11,\"email\":\"kelly.williams@example.com\",\"phoneNumber\":\"214-555-1234\",\"customerName\":\"Kelly Williams\",\"country\":\"USA\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/12",
				"mimeType": "application/json",
				"text": "{\"id\":12,\"email\":\"liam.martinez@example.com\",\"phoneNumber\":\"972-555-5678\",\"customerName\":\"Liam Martinez\",\"country\":\"Canada\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/13",
				"mimeType": "application/json",
				"text": "{\"id\":13,\"email\":\"mia.anderson@example.com\",\"phoneNumber\":\"469-555-9012\",\"customerName\":\"Mia Anderson\",\"country\":\"UK\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/14",
				"mimeType": "application/json",
				"text": "{\"id\":14,\"email\":\"noah.thomas@example.com\",\"phoneNumber\":\"817-555-3456\",\"customerName\":\"Noah Thomas\",\"country\":\"Australia\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/15",
				"mimeType": "application/json",
				"text": "{\"id\":15,\"email\":\"olivia.jackson@example.com\",\"phoneNumber\":\"682-555-7890\",\"customerName\":\"Olivia Jackson\",\"country\":\"Germany\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/16",
				"mimeType": "application/json",
				"text": "{\"id\":16,\"email\":\"owen.white@example.com\",\"phoneNumber\":\"214-555-2345\",\"customerName\":\"Owen White\",\"country\":\"France\"}"
			},
			{
				"uri": "http://localhost:9926/Customers/17",
				"mimeType": "application/json",
				"text": "{\"id\":17,\"email\":\"sophia.harris@example.com\",\"phoneNumber\":\"972-555-6789\",\"customerName\":\"Sophia Harris\",\"country\":\"Japan\"}"
			}
		]
	}
}

Querying Tables

When retrieving data from tables using resources/read, you can use optional query parameters in the URI to filter data.

Filtering: Use attribute=value pairs to filter based on column values. The comparator is always "equals".
- Example: http://localhost:9925/my_table?name=John&city=NewYork
Pagination: Use limit and start parameters for pagination.
- limit: Maximum number of results to return.
- start: Offset to start returning results from.
- Example: http://localhost:9925/my_table?limit=10&start=20

Error Responses

The server returns standardized JSON-RPC error responses:

{
	"jsonrpc": "2.0",
	"id": 2,
	"error": {
		"code": -32602,
		"message": "Invalid params."
	}
}

Error Codes:

-32601: Method not found.
-32602: Invalid params.
-32603: Internal server error.

Harper MCP Server