Harper 5.1 Makes Your Applications MCP-Native

Harper 5.1 ships a complete MCP (Model Context Protocol) server implementation. Any MCP-compatible client — Claude Desktop, Cursor, Copilot Studio, or your own agent — can connect directly to a Harper instance, read and write records, and invoke operations through a standardized protocol.

The notable part isn't just that Harper speaks MCP. It's that Harper generates its tools automatically from your application's schema. When you deploy a component with HTTP resource handlers, Harper surfaces those as callable MCP tools without you writing any adapter code.

How it works

Harper's MCP server runs on two transports:

• Streamable HTTP (spec 2025-06-18) on both the operations port and the application port
• stdio, via the new harper mcp CLI, for local agent integrations

Sessions are stored in a native system.mcp_session Harper table with TTL-based expiration, so there's no separate session store to manage. Sliding-window idle TTL means active sessions stay alive; idle ones expire automatically.

Tool generation

Two categories of tools are auto-generated:

Operations tools surface Harper's management operations — describe_table, insert, search_by_value, and so on — scoped to what the authenticated user can actually do. RBAC applies at the tools/list level, so a user who can't write to a table won't see write tools for it.

Application tools are generated from your deployed component's HTTP resource handlers. Harper inspects the exported schema and emits a tool per operation. Custom resources can opt in explicitly via static mcpTools to control the tool name, description, and parameter schema:

export class ProductSearch extends Resource {
  static mcpTools = {
    search: {
      description: 'Search products by semantic similarity',
      inputSchema: {
        type: 'object',
        properties: {
          query: { type: 'string' },
          limit: { type: 'number', default: 10 }
        },
        required: ['query']
      }
    }
  };

  async get(query) {
    // ...
  }
}

RBAC and audit

Every tool call is logged to an audit trail. Each MCP session has its own rate-limit bucket, with separate limits for read and write operations. The limits are configurable; the defaults are conservative. Session IDs are bound to the authenticated user, so a leaked session ID can't be used by a different user.

listChanged notifications are supported — clients with active subscriptions receive updates when tables or components change while a session is open.

Getting started

If you're running Harper locally and want to connect Claude Desktop, the quickest path is the stdio transport:

harper mcp --profile default

This starts a stdio MCP server authenticated against your local instance. Running harper mcp doctor will confirm the connection resolves cleanly and show which tools are visible.

For a remote or production connection, add an mcp block to your Harper config and point your client at https://your-harper-host/mcp. The Streamable HTTP transport handles reconnection and session resumption automatically.

Tradeoffs and current limitations

Tool names are derived from operation names and HTTP method + path, which can produce verbose names for complex schemas. The static mcpTools opt-in is the current mechanism for controlling this — a more general alias layer isn't in 5.1.

Full-table list tools without a filter predicate can be expensive. If you're letting an agent drive queries across large tables, scoping the exported schema or using static mcpTools to constrain inputs is worth doing upfront.

The tools surface is built to evolve: the tool registry and dispatch architecture in 5.1 is designed to accept additional tool categories (like vector search tools tied to HNSW indexes) as follow-on work.