Custom Enterprise MCP Integration Guide
Overview
Custom enterprise access is for in-house assistants and other platforms that support Streamable HTTP MCP. The platform passes a unique identifier for the current member. GuanMCP matches the corresponding Guandata BI user property, and permissions follow the matched user.
Connect a custom enterprise platform
Prerequisites
- Configure centralized access with
MCP_ENTRYPOINT_TOKENandBI_APP_TOKEN. - Ensure the platform dynamically passes a stable, unique identifier such as a Coze user ID.
- Store the same identifier in a Guandata BI user property so it uniquely identifies one enabled user.
Step 1: Define user mapping
Choose the identity header supplied by the platform and the Guandata user property that stores the same identifier. This example maps a Coze user ID to the custom BI property CozeID through x-aiplugin-connector-identifier.
| Item | Example | Description |
|---|---|---|
| Identity header | x-aiplugin-connector-identifier | Header dynamically sent for the current member. |
| Guandata user property key | 74970c76-114d-cf73-8403-c5dc1a954952 | Internal key of the custom BI property CozeID. |
| Property value | 123 | Identifier that must match exactly and remain unique. |
Replace the example UUID with the actual internal key of CozeID in your BI environment. Do not use the display name CozeID as the key. For many users, maintain mappings through an Account Dataset and Account Sync. For a few users, edit user information directly.
Step 2: Configure GuanMCP
MCP_ENTRYPOINT_TOKEN=<MCP service credential>
BI_APP_TOKEN=<Guandata Public API application token>
Step 3: Add GuanMCP to the enterprise platform
- Add a Streamable HTTP MCP service with the complete URL, such as
https://mcp.company.com/mcp. - Configure
Authorization: Bearer <MCP service credential>. - Configure
bi-user-property-header: x-aiplugin-connector-identifierandbi-user-property-key: 74970c76-114d-cf73-8403-c5dc1a954952as custom headers on the platform or trusted gateway, replacing the example property key with the actual internal key. - Have the platform dynamically populate
x-aiplugin-connector-identifierfor the authenticated user. Send both mapping headers and the identity value with every request.
POST https://mcp.company.com/mcp
Authorization: Bearer <MCP service credential>
bi-user-property-header: x-aiplugin-connector-identifier
bi-user-property-key: 74970c76-114d-cf73-8403-c5dc1a954952
x-aiplugin-connector-identifier: 123
The identity value must not be fixed. End users must not supply mapping or identity headers themselves. Do not configure a personal PAT, BI password, or BI_APP_TOKEN in the enterprise AI platform.
Step 4: Verify access
Ask “Show me the datasets I can access” as two members with different permissions and verify that each request contains that member's identifier. Results should match their Guandata BI permissions.
Troubleshooting
User identity is missing
Verify that the platform dynamically sends the header specified by bi-user-property-header. Specifying a header name does not make the upstream platform generate an identifier.
User mapping fails
Compare the request header value with the Guandata property specified by bi-user-property-key. Values must match exactly and identify one enabled user.
Different members receive identical results
Verify the identity header changes with the member and that the two users actually have different Guandata BI permissions. Never use one fixed BI account for all members.