HiAgent MCP Server

This MCP server wraps HiAgent Platform OpenAPI capabilities as MCP tools. It currently provides knowledge-engine tools — listing knowledge bases (datasets) in a workspace, inspecting a dataset, and calling the HiAgent knowledge engine to retrieve knowledge chunks — and will keep adding more HiAgent OpenAPI capabilities over time.

Features

• List knowledge bases (datasets) in a workspace
• Inspect a single dataset, including its default retrieval parameters
• Search knowledge in one or more datasets via the knowledge engine (knowledge_search)
• Report MCP server and OpenAPI configuration state

Setup

Prerequisites

• Python 3.11 or higher
• API credentials (AK/SK)

Installation

Run directly from the repository with uvx (recommended):

uvx --from "git+https://github.com/volcengine/mcp-server#subdirectory=server/mcp_server_hiagent" mcp-server-hiagent

Or with uv, from the compatibility path:

cd mcp-server/server/mcp_server_hiagent
uv run mcp-server-hiagent

Configuration

The server requires the following environment variables:

• HIAGENT_TOP_HOST: HiAgent Platform API (volc-top) gateway address, including scheme and port
• HIAGENT_ACCESS_KEY_ID: Your HiAgent access key id
• HIAGENT_SECRET_ACCESS_KEY: Your HiAgent secret access key

Optional environment variables:

• HIAGENT_VERSION: HiAgent OpenAPI compatibility version to use. Defaults to the latest registered version (currently v3.1.0). Can also be set per-run with the --hiagent-version CLI flag, which takes precedence. Selects a self-contained implementation under versions/; supported values: v3.1.0
• HIAGENT_ACCOUNT_ID: Main account id sent as the X-Account-Id query parameter, defaults to 1000000000
• HIAGENT_REGION: Region used in AK/SK V4 signing (not a network address), defaults to cn-north-1
• FASTMCP_CHECK_FOR_UPDATES: Set to off to skip FastMCP's startup update check, which otherwise makes an outbound request and can fail startup in restricted networks
• MCP_SERVER_HOST: Bind host for the FastMCP server, streamable-http only (default: 127.0.0.1)
• MCP_SERVER_PORT: Bind port for the FastMCP server, streamable-http only (default: 8000)
• STREAMABLE_HTTP_PATH: Streamable HTTP endpoint path (default: /mcp)

Usage

Running the Server

The server can be run with either stdio transport (for MCP integration, e.g. the HiAgent STDIO plugin) or streamable-http transport:

python -m mcp_server_hiagent.main --transport stdio

Or:

python -m mcp_server_hiagent.main --transport streamable-http

Select a specific HiAgent OpenAPI version explicitly with --hiagent-version (overrides the HIAGENT_VERSION environment variable; defaults to the latest registered version):

python -m mcp_server_hiagent.main --hiagent-version v3.1.0

Available Tools

health_check

Report the MCP server and OpenAPI configuration state.

health_check()

list_datasets

List knowledge bases (datasets) in a workspace, so callers can obtain the DatasetIDs required by the knowledge engine.

list_datasets(
    workspace_id="workspace_id",
    page_number=1,
    page_size=20,
)

Parameters:

• workspace_id (required): the workspace id to list datasets for.
• page_number (optional): page number (default: 1).
• page_size (optional): page size (default: 20).

get_dataset

Get information about a single dataset, including its default retrieval parameters.

get_dataset(
    workspace_id="workspace_id",
    dataset_id="dataset_id",
)

Parameters:

• workspace_id (required): the workspace id the dataset belongs to.
• dataset_id (required): the id of the dataset to inspect.

call_knowledge_engine_tool

Call the HiAgent knowledge engine over one or more datasets. Only tool_name="knowledge_search" is supported at present.

call_knowledge_engine_tool(
    workspace_id="workspace_id",
    dataset_ids=["dataset_id"],
    tool_name="knowledge_search",
    queries=["How to reset my password?"],
    top_k=3,
    score_threshold=0.2,
)

Parameters:

• workspace_id (required): the workspace id the datasets belong to.
• dataset_ids (required): list of dataset ids to search, at least one.
• tool_name (optional): sub-tool name, defaults to knowledge_search. Only knowledge_search is supported at present; other known sub-tools (list_knowledge_chunks, grep_chunks, get_doc_info, wiki_search, wiki_read_page, wiki_read_source_doc) are recognized but rejected.
• queries (optional): list of query strings (required for knowledge_search).
• top_k (optional): maximum number of results to return.
• score_threshold (optional): relevance score threshold (0~1).
• rerank_id (optional): rerank model id.
• knowledge_run_mode (optional): run mode, one of quick / smart_search / wiki_search.

Best Practices & Test Prompts

Recommended usage pattern and, for each exposed tool, a natural-language prompt you can give an MCP-enabled agent to exercise it plus the expected result. These prompts double as a manual smoke test after wiring the server into a client.

Recommended flow: health_check (confirm config) → list_datasets (discover DatasetIDs) → optionally get_dataset (read default retrieval params) → call_knowledge_engine_tool (retrieve). WorkspaceID is not discoverable via this server — take it from the HiAgent console URL (.../workspace/<id>/...).

health_check

• Best practice: call it first, before any credentialed tool, to confirm the server sees your AK/SK and top host. It never calls the OpenAPI and never echoes secrets — only booleans.
• Test prompt: "Check whether the HiAgent MCP server is healthy and properly configured."
• Expected result: status="ok", auth="aksk", and configured=true with each *_configured flag true when env vars are set; no credential values are returned.

list_datasets

• Best practice: use it to discover the DatasetIDs required by call_knowledge_engine_tool; page with page_number/page_size (1–100) instead of requesting everything at once. dataset == knowledge base.
• Test prompt: "List the knowledge bases in workspace <workspace_id>."
• Expected result: a paged list of datasets, each with its id and name, that you can feed into the knowledge engine.

get_dataset

• Best practice: call it when you want a dataset's default retrieval parameters (e.g. RetrievalTopK, RetrievalScoreThreshold) so your call_knowledge_engine_tool arguments match how the base was configured.
• Test prompt: "Show the details and default retrieval settings of dataset <dataset_id> in workspace <workspace_id>."
• Expected result: the dataset's metadata including its default retrieval parameters.

call_knowledge_engine_tool

• Best practice: pass 1–5 short, self-contained queries (not a whole conversation); start with a small top_k (e.g. 3) and a modest score_threshold (e.g. 0.2), then tune. Only tool_name="knowledge_search" is supported in this version.
• Test prompt: "Search datasets [<dataset_id>] in workspace <workspace_id> for "How do I reset my password?" and return the top 3 chunks."
• Expected result: a Result.KnowledgeSearch.Hits[] payload where each hit carries DatasetID / DocumentID / SegmentID / Content; an unsupported tool_name is rejected with a clear error, and invalid arguments (empty queries, score_threshold outside 0–1) raise a validation error.

MCP Integration

To add this server to your MCP configuration, add the following to your MCP settings file:

{
  "mcpServers": {
    "hiagent": {
      "command": "uvx",
        "args": [
          "--from",
          "git+https://github.com/volcengine/mcp-server#subdirectory=server/mcp_server_hiagent",
          "mcp-server-hiagent"
        ],
      "env": {
        "HIAGENT_TOP_HOST": "http://your-top-host:30040",
        "HIAGENT_ACCESS_KEY_ID": "your-access-key",
        "HIAGENT_SECRET_ACCESS_KEY": "your-secret-key",
        "HIAGENT_ACCOUNT_ID": "1000000000",
        "HIAGENT_REGION": "cn-north-1",
        "FASTMCP_CHECK_FOR_UPDATES": "off"
      }
    }
  }
}

This uses the STDIO transport (the default), which the HiAgent MCP plugin launches locally and injects credentials into via its environment-variable table.

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your AK/SK credentials are correct
   • Check that you have the necessary permissions for the workspace and datasets

2. Startup Failure in Restricted Networks

   • Set FASTMCP_CHECK_FOR_UPDATES=off to skip FastMCP's outbound update check

3. Empty or Denied Results

   • Verify the workspace_id and dataset_ids are correct
   • Confirm HIAGENT_TOP_HOST points to the HiAgent Platform API (volc-top) gateway, not the web or Agent API address

Logging

The server uses Python's logging module with INFO level by default. You can see detailed logs in the console when running the server.

License

volcengine/mcp-server is licensed under the MIT License.