GuanMCP Integration and User Guide

Last updated: 2026-08-31 17:54:02

Overview

GuanMCP connects MCP-compatible AI clients to Guandata BI. Users can search BI resources, understand metric definitions, and query authorized data in natural language. GuanMCP is read-only: it does not create, modify, or delete BI resources, and it never bypasses Guandata BI permissions.

Connect to GuanMCP

Step 1: Choose an access method

Access method	Recommended for	Identity and permissions
Centralized administrator-managed access with individual member identities	Custom enterprise AI platforms	An administrator provides one Streamable HTTP service. Each request carries the current user's identity, and access follows that user's Guandata BI permissions.
Individual access with a personal PAT or account	Small teams, specific departments, and local individual use	Each member configures personal credentials in their MCP client, and access follows the credential owner's permissions.

Choose the access method supported by the GuanMCP endpoint provided by your administrator. Individual access supports either a remote service or a locally started service. A PAT is recommended for individual access.

Step 2: Complete the connection

Centralized administrator-managed access

1. Confirm that the AI platform can pass a unique attribute of the current user with every request and that the attribute has been synchronized to the user's Guandata BI profile.

2. Configure the standard GuanMCP service:

   Setting	Description
   MCP_ENTRYPOINT_TOKEN	MCP service credential used in Authorization: Bearer <MCP service credential>.
   BI_APP_TOKEN	Guandata Public API application token used for server-side identity exchange. Never send it from a client.

   MCP_ENTRYPOINT_TOKEN=<MCP service credential>
   BI_APP_TOKEN=<Guandata Public API application token>

   Configure two custom request headers on the AI platform: bi-user-property-header specifies the header carrying the current user's attribute value, and bi-user-property-key specifies the internal key of the corresponding Guandata user property. For a custom property, use its actual internal key, not its display name.

   Platform	bi-user-property-header	bi-user-property-key	Mapping
   Custom enterprise AI platform	Platform-defined identity header	Corresponding user property key	Platform identifier → Guandata user property

   With a GuanMCP service that supports these headers, platforms can specify mappings per request and share the same service. Each request must include both mapping headers and the corresponding user attribute value. Incomplete or invalid configuration returns an error. Only when both mapping headers are absent does the service fall back to the existing BI_USER_PROPERTY_HEADER and BI_USER_PROPERTY_KEY environment variables.

   For many users, maintain mappings through an Account Dataset and Account Sync. For a few users, edit user information directly. Attribute values must exactly match the member identifiers passed by the platform and must be unique.

3. Add a Streamable HTTP MCP service to the AI platform. Enter the complete URL and configure MCP_ENTRYPOINT_TOKEN in the Authorization header.

4. Ensure every request carries both mapping headers and the current user's attribute value, injected by the authenticated platform or a trusted gateway. For example:

   POST https://bi.example.com/mcp
   Authorization: Bearer <MCP service credential>
   bi-user-property-header: X-Company-User-Id
   bi-user-property-key: <actual internal user property key>
   X-Company-User-Id: <current user attribute value>

5. Ask the same question as two members with different BI permissions. Each result should match that member's Guandata BI permissions.

Risk

MCP_ENTRYPOINT_TOKEN protects the MCP entry point; BI_APP_TOKEN is only for server-side identity exchange. Never interchange them. The gateway for centralized identity mapping must discard externally supplied direct Guandata credentials, mapping headers, and identity headers, including X-Personal-Token, X-GuanBI-Uid-Token, X-GuanBI-Login-Id, and the platform identity header. It must then inject the platform's fixed mapping headers and the authenticated user's identity to prevent impersonation or bypassing user mapping. Never expose real tokens in chats, screenshots, tickets, or repositories.

For a centralized administrator-managed integration, see the custom enterprise guide.

Individual access

Each member configures personal credentials in their own MCP connection. Access follows the credential owner's BI permissions and authorized scope.

Connect to a remote service with a personal PAT

Use this method when a remote GuanMCP endpoint is available and the client supports Streamable HTTP and custom headers. No local Node.js installation or GuanMCP process is required.

1. Obtain the complete HTTPS MCP endpoint that supports personal PAT access from your administrator. If the centralized identity-mapping endpoint filters personal credentials, use the separate personal PAT endpoint provided by the administrator.

2. Sign in to the BI environment associated with that service and create your own PAT.

3. Enter the service URL in your personal MCP connection and set X-Personal-Token to your PAT. For clients that accept JSON configuration:

   {
     "mcpServers": {
       "guanbi": {
         "url": "https://bi.example.com/mcp",
         "headers": {
           "X-Personal-Token": "<your personal PAT>"
         }
       }
     }
   }

4. Save and reconnect. Ask “Show me the datasets I can access” and confirm that only authorized resources are returned. Then complete connection verification.

Personal PAT access requires no additional Authorization header, BI_APP_TOKEN, or user identity header. Do not substitute Authorization: Bearer <PAT> for X-Personal-Token. Use the complete endpoint path supplied by the administrator, such as https://bi.example.com/mcp.

Each member must use their own PAT. Never configure one person's PAT as a shared agent credential: all requests would run as that BI user instead of switching with the current conversation member. When a PAT expires or becomes invalid, update it in the personal connection and reconnect.

PAT mode supports ordinary BI tools only, not ChatBI tools. See the PAT guide for limitations.

Start GuanMCP locally with stdio

Use this method when the MCP client can start a local service.

1. Sign in to Guandata BI and create a personal PAT as described in the PAT User Guide. If the entry is unavailable, ask your BI administrator to check the environment and your permissions.

2. Install Node.js 20 or later and make sure npx is available.

3. Add the following configuration and replace the sample values:

   {
     "mcpServers": {
       "guanbi": {
         "command": "npx",
         "args": ["-y", "@guandata/guanbi-mcp-server@latest"],
         "env": {
           "BI_BASE_URL": "https://bi.example.com",
           "BI_PAT": "<personal PAT>"
         }
       }
     }
   }

4. Save the configuration and reload the MCP service.

PAT is recommended because its permissions, expiration, and revocation can be managed independently. If PAT is unavailable, use a personal account:

{
  "BI_BASE_URL": "https://bi.example.com",
  "BI_LOGIN_ID": "<login account>",
  "BI_LOGIN_PASSWORD": "<login password>"
}

BI_LOGIN_DOMAIN defaults to guanbi. If your login domain differs, confirm it with your BI administrator and add this setting. Account credentials are stored locally, so use this method only when it meets your organization's security requirements.

Step 3: Verify the connection

Ask:

1. “What BI capabilities are currently available through GuanMCP?”
2. “Show me the datasets I can access.”
3. “Query this week's East China sales and identify the metric, card, or dataset used.”

The connection is successful if GuanMCP tools appear, authorized resources are found, and the result includes verifiable data sources.

Use GuanMCP

Purpose	Example prompt
Find resources	Find pages, cards, and datasets whose names contain “Store Operations.”
Understand definitions	What is the definition of the Sales metric, and which dimensions are available?
Query data	Query this week's East China sales and compare them with last week.
Continue analysis	Break down the sales change by city, list the three largest changes, and cite the data source.

Specify the time range, business scope, target metric or resource, and desired output. If the resource name is unknown, ask the AI to list candidates first.

Permissions and capability boundaries

• Results follow the current user's resource permissions, organizational scope, and row- and column-level permissions.
• Metric Platform, Metric Tree, and ChatBI depend on the modules enabled in the environment. PAT mode does not provide ChatBI tools.
• GuanMCP searches resources, reads configurations, and queries data. It does not create, modify, publish, or bulk-export BI resources.

Troubleshooting

This page does not repeat detailed troubleshooting steps. For HTTP, session, stdio, pagination, UTF-8, or SQL issues, see GuanMCP Troubleshooting.

Related documents

• Custom Enterprise MCP Integration Guide
• GuanCLI vs. GuanMCP
• GuanCLI User Guide
• GuanMCP Troubleshooting