HAP

HAP MCP Server provides a production‑ready MCP (Model Context Protocol) server that enables seamless integration of AI capabilities with Mingdao’s Hyper Application Platform. It supports both local stdio (CLI) and HTTP transport, exposes a complete set of HAP API tools, and is designed for enterprise‑grade reliability and extensibility.

How to use

You use the HAP MCP server by running it locally (stdio) or exposing it over HTTP, then connect your MCP client (for example Cursor) to access the HAP API tools directly in your AI conversations. You can run the server in stdio mode for local tooling and development, or start the HTTP server for web‑based integration. When using a client, provide the necessary environment variables and, if you are deploying privately, the custom host when required.

To connect Cursor or another MCP client, configure an MCP server entry that points to the local stdio CLI start command. You will typically run the server with a command like npm start and supply the required credentials via environment variables such as APPKEY and SIGN. In private deployments, you also provide HOST to direct API calls to your private MCP server.

How to install

Prerequisites you need before you install and run the server: Node.js 18 or newer.

1. Install dependencies and prepare the project. Use your preferred package manager to install the required packages.

2. Start the stdio server to run MCP tools locally.

3. Start the HTTP server to expose the MCP API over HTTP when you need network access.

4. For development with auto‑reload, run the development commands provided for your environment.

Configuration and usage notes

Environment variables are used to configure access and host information. Required values include APPKEY and SIGN. Optional values include HOST for private deployments. When you set HOST, API calls will use host/api instead of the default api.mingdao.com.

For a private deployment, place your private server URL in HOST and ensure your client points to the correct local or remote endpoints. When using Cursor, you can configure a global or per‑workspace mcp.json with the following patterns.

{
  "mcpServers": {
    "hap-mcp": {
      "command": "npx",
      "args": ["-y", "@mingdaocloud/hap-mcp"],
      "env": {
        "APPKEY": "your_APPKEY_here",
        "SIGN": "your_signature_here"
      }
    }
  }
}

Testing and validation

You can test the MCP server using built‑in CLI tools and validate responses from the HAP API. Use the provided test commands to ensure the server is reachable and the API surface behaves as expected.

Transport methods overview

The MCP server supports two transport modes: stdio (CLI) and HTTP (web mode). Stdio runs on your local machine and is ideal for development and personal tooling. HTTP runs over the network and is suitable for team collaboration and shared tools.

Connecting to the server from a client

Connect your client to the MCP server by configuring either a stdio command or an HTTP URL. The stdio path uses your local command to start the server, while the HTTP path uses a public or private URL to reach the server over the network.

Custom tools and resources

You can extend the MCP server by adding custom tools, resources, and prompts. Examples show how to register a tool, a resource template, and a prompt so that your AI workflows can leverage new capabilities.

Notes on deployment

When deploying privately, ensure the HOST value is set to your private deployment URL. For public usage, you can rely on the default host configuration. You may choose to run the stdio server for local development or the HTTP server for collaborative use across machines.

Troubleshooting

If you encounter connection issues, verify that APPKEY and SIGN are correctly set in the environment. If using a private deployment, confirm that HOST points to the correct private server. Check that the server is running in the intended transport mode (stdio or HTTP) and that your client is configured to connect to the proper endpoint.

Available tools

add_worksheet_record

Add a new record to a worksheet.

delete_worksheet_record

Delete a record from a worksheet.

update_worksheet_record

Update an existing worksheet record.

get_worksheet_fields

Retrieve information about worksheet fields.

list_worksheet_records

List records with filtering and pagination.

list_worksheets

List all worksheets in the application.

get_worksheet_pivot_data

Fetch pivot table data with aggregation.

create_worksheet

Create a new worksheet with controls.

get_worksheet_record_detail

Get detailed information for a specific record.

add_worksheet_records_batch

Bulk create multiple worksheet records.

update_worksheet_records_batch

Bulk update multiple worksheet records.

get_app_info

Retrieve application information including groups, worksheets, and pages.

get_related_worksheet_records

Get records from linked worksheets.

get_worksheet_record_share_link

Generate sharing links for worksheet records.

get_worksheet_record_count

Get total record count in worksheets.

get_worksheet_record_logs

Get operation history for records.

get_roles

List application roles.

create_role

Create roles with permissions.

delete_role

Delete roles.

add_role_members

Add users to roles.

remove_role_members

Remove users from roles.

get_role_detail

Get detailed information about a role.

exit_app

Remove a user from the application.

create_option_set

Create new option sets.

get_option_set

Get option set details.

update_option_set

Update existing option sets.

delete_option_set

Delete option sets.

get_area_info

Retrieve geographical area information.