Harper MCP Server
by
Provides a Model Context Protocol (MCP) compatible API server that exposes HarperDB tables and custom resources as structured JSON‑RPC resources, enabling read‑only data access, filtering, and pagination.
Harper MCP Server Overview
What is Harper MCP Server about?
The server implements MCP methods resources/list and resources/read on a single /mcp endpoint, translating HarperDB tables and custom resources into JSON‑RPC 2.0 calls. It returns standardized resource descriptors and data payloads, supports query‑parameter filtering, pagination, and consistent error handling.
How to use Harper MCP Server?
- Deploy the component to a running HarperDB instance (Harper 4.5.10+). Example via Harper Operation API:
{
"operation": "deploy_component",
"package": "@harperdb/mcp-server@1.0.0"
}
- Ensure the environment variable
HOSTis set to the base URL of the server – it is used to build resource URIs. - Send JSON‑RPC POST requests to
/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" } }
- List resources:
- Use 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 on a single
/mcpendpoint - Automatic discovery of HarperDB tables and custom resources (
resources/list) - Read‑only data retrieval with filtering and pagination (
resources/read) - Static capabilities endpoint (
/capabilities.json) - Standardized error responses with JSON‑RPC error codes
- Leverages HarperDB’s built‑in authentication (Basic, JWT, mTLS)
Use cases of Harper MCP Server
- Expose database tables to external services that consume MCP‑style resources
- Build low‑latency, geo‑distributed data access layers without maintaining separate APIs
- Enable rapid prototyping of data‑driven applications that require structured resource discovery
- Integrate HarperDB data into generic MCP clients or orchestration platforms
FAQ from the Harper MCP Server
Q: What HarperDB version is required? A: Version 4.5.10 or later.
Q: Can I modify data through the MCP server? A: The server provides read‑only access only.
Q: How are authentication credentials passed? A: Use HarperDB’s standard authentication mechanisms (Basic Auth, JWT, mTLS) on the HTTP request.
Q: Where can I find the list of supported MCP methods?
A: Currently resources/list and resources/read are implemented.
Q: How do I enable custom resources?
A: Register a custom resource path in HarperDB; the server will expose it under {HOST}/{path}/{resource_name}.
Harper MCP Server's README
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.
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
- Example:
-
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)
- Example:
-
Custom Resources: Custom resources are accessed via URIs defined by their registered path:
{HOST}/{path}/{resource_name}- Example:
http://localhost:9925/custom/my_resource
- Example:
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=valuepairs to filter based on column values. The comparator is always "equals".- Example:
http://localhost:9925/my_table?name=John&city=NewYork
- Example:
- Pagination: Use
limitandstartparameters 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 Reviews
Login Required
Please log in to share your review and rating for this MCP.
Actions
Harper MCP Server's Information
Configuration
{
"mcpServers": {
"harper-mcp-server": {
"command": "npx",
"args": [
"-y",
"@harperdb/mcp-server"
],
"env": {}
}
}
}Configure Clients
Related MCP Servers
Discover more MCP servers with similar functionality and use cases
MCP Toolbox For Databases
by googleapis
Provides a configurable MCP server that abstracts connection pooling, authentication, observability, and tool management to accelerate development of database‑backed AI tools.
DBHub
by bytebase
DBHub is a universal database gateway that implements the Model Context Protocol (MCP) server interface, enabling MCP-compatible clients to interact with various databases.
Neo4j MCP Clients & Servers
by neo4j-contrib
Provides Model Context Protocol servers for interacting with Neo4j databases, managing Aura instances, and handling personal knowledge graph memory through natural‑language interfaces.
MongoDB MCP Server
by mongodb-js
Provides a Model Context Protocol server that connects to MongoDB databases and Atlas clusters, exposing a rich set of tools for querying, managing, and administering data and infrastructure.
MySQL
by benborla
A Model Context Protocol (MCP) server that provides read-only access to MySQL databases, enabling Large Language Models (LLMs) to inspect database schemas and execute read-only queries.
Mcp Clickhouse
by ClickHouse
Provides tools that let AI assistants run read‑only SQL queries against ClickHouse clusters or the embedded chDB engine, plus a health‑check endpoint for service monitoring.
Elasticsearch MCP Server
by elastic
Provides direct, natural‑language access to Elasticsearch indices via the Model Context Protocol, allowing AI agents to query and explore data without writing DSL.
MotherDuck DuckDB MCP Server
by motherduckdb
Provides an MCP server that enables SQL analytics on DuckDB and MotherDuck databases, allowing AI assistants and IDEs to execute queries via a unified interface.
Redis MCP Server
by redis
Provides a natural language interface for agentic applications to manage and search data in Redis efficiently.