Harper
Created 5 months ago
A server implementation of the Model Context Protocol (MCP) for exposing data in HarperDB.
What is Harper?
An MCP server providing an interface for MCP clients to access data within [Harper](https://www.harpersystems.dev/).
Documentation
Harper MCP Server
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
HOSTshould 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.
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,/mcphandles all requests. The server uses JSON-RPC 2.0 for communication.
Resource URIs
- Tables: Resources representing HarperDB tables are accessed via URIs like:
{HOST}/{table_name} - Table Rows: Individual rows within a table can be accessed using the primary key:
{HOST}/{table_name}/{primary_key_value} - Custom Resources: Custom resources are accessed via URIs defined by their registered path:
{HOST}/{path}/{resource_name}
Usage
- Listing Resources
- Get resources data
Querying Tables
When retrieving data from tables using resources/read, you can use optional query parameters in the URI to filter data.
Error Responses
The server returns standardized JSON-RPC error responses.
Server Config
{
"mcpServers": {
"harper-server": {
"command": "npx",
"args": [
"harper"
]
}
}
}