GuanMCP Deployment Guide

Deployment Overview

GuanMCP supports two deployment modes: local stdio mode and production streamable-http mode.

Mode	Scenario	Description
`stdio`	Personal desktop clients, demos, development debugging	The MCP client starts a local GuanMCP process, usually representing one fixed user accessing one BI site.
`streamable-http`	Enterprise AI platform or gateway integration	GuanMCP runs as a resident HTTP service. Clients call it through `POST /mcp`.

stdio is a local fixed-user solution and is not suitable for enterprise multi-user access. For enterprise multi-user scenarios, use streamable-http mode and deploy through Kubernetes, an enterprise container platform, or a gateway.

The Kubernetes ConfigMap, Secret, Deployment, and Service are the base deployment files. For Feishu Aily integration, add a small amount of configuration on top of the base deployment.

Roles and Responsibilities Before Deployment

GuanMCP usually requires collaboration among BI administrators, IT/O&M, and AI platform administrators.

Item	Recommended Owner	Description
BI access URL and public path	BI administrator / O&M	Confirm `BI_BASE_URL` and `BI_PUBLIC_PATH`.
MCP service domain, gateway, and certificate	IT/O&M	Confirm that the external AI platform can access `/mcp`.
Entry authentication token	IT/O&M	Generate and manage `MCP_ENTRYPOINT_TOKEN` through Secret.
Account synchronization token	BI administrator	Obtain the token from GuanBI before deployment and write it to Secret as `BI_APP_TOKEN`.
User identity mapping	BI administrator / AI platform administrator	Confirm how users from Aily, DecideX, or a self-built assistant map to GuanBI users. For Aily, email mapping is recommended.
Pilot resources and test accounts	BI administrator / business owner	Prepare pilot metrics, pages, ChatBI topics, and accounts with different permissions.

For demos or development debugging, you can start with local stdio or temporary fixed-user HTTP validation. For production multi-user use, switch to real user identity passing and permission isolation.

Local stdio Deployment

Local stdio mode is suitable for personal desktop clients, demos, and development debugging. The client starts a local GuanMCP process that accesses one BI site as one fixed user.

Choose one:

Login Method	Description
`BI_UID_TOKEN`	Log in with the current user's token.
`BI_LOGIN_DOMAIN`, `BI_LOGIN_ID`, `BI_LOGIN_PASSWORD`	Log in with account and password.

Client Configuration Example

Add the service configuration in an MCP-supported client. The core settings are BI URL and current-user login information.

{
  "mcpServers": {
    "guanbi": {
      "command": "npx",
      "args": ["-y", "@guandata/guanbi-mcp-server@latest"],
      "env": {
        "BI_BASE_URL": "https://your-bi-host.example.com",
        "BI_UID_TOKEN": "current-user-token"
      }
    }
  }
}

If using account/password login, replace BI_UID_TOKEN with the corresponding account/password environment variables.

Production HTTP Deployment

Production should use streamable-http mode. The image listens on 0.0.0.0:9090 by default.

Key Endpoints

Endpoint	Purpose
`POST /mcp`	MCP call entry
`GET /healthz`	Health check
`GET /sysmon/health/liveness`	Liveness probe
`GET /sysmon/health/readiness`	Readiness probe

Routing Suggestions

Prefer a dedicated domain, such as https://guanbi-mcp.example.com/mcp.
If reusing the BI domain, use an independent prefix and rewrite it to backend /mcp in the gateway.
Multiple replicas require sticky routing by Mcp-Session-Id. If sticky routing cannot be configured, start with a single replica.

Prepare Before Deployment

Confirm BI Access URL

In guanbi-mcp-server-configmap.yaml, set BI_BASE_URL to the actual BI URL accessible by the customer.

BI_BASE_URL: "https://your-bi-host.example.com"

Configure BI_PUBLIC_PATH according to the BI access path:

BI Access Method	BI_PUBLIC_PATH
No path prefix, such as `https://bi.example.com`	`/`
With path prefix, such as `https://bi.example.com/guanbi`	`/guanbi`

BI_PUBLIC_PATH: "/"
# or
BI_PUBLIC_PATH: "/guanbi"

Generate MCP Entry Token

MCP_ENTRYPOINT_TOKEN is used by clients to connect to the MCP service. Generate it separately and inject it through Kubernetes Secret.

openssl rand -base64 32

Create guanbi-mcp-server-secret.yaml:

apiVersion: v1
kind: Secret
metadata:
  name: guanbi-mcp-server
type: Opaque
stringData:
  MCP_ENTRYPOINT_TOKEN: "<replace_with_generated_token>"

Send the generated token securely. Do not commit real tokens to code repositories, ticket attachments, or public documents.

Kubernetes Configuration Files

guanbi-mcp-server-configmap.yaml

kind: ConfigMap
apiVersion: v1
metadata:
  name: guanbi-mcp-server
data:
  MCP_TRANSPORT: streamable-http
  MCP_HTTP_HOST: "0.0.0.0"
  MCP_HTTP_PORT: "9090"
  BI_BASE_URL: "https://your-bi-host.example.com"
  BI_PUBLIC_PATH: "/"
  BI_REQUEST_TIMEOUT_MS: "120000"
  BI_MAX_ROWS: "1000"
  GUANBI_MCP_USAGE_STATS: ""
  MCP_TRUSTED_GATEWAY: "false"

guanbi-mcp-server-secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: guanbi-mcp-server
type: Opaque
stringData:
  MCP_ENTRYPOINT_TOKEN: "<replace_with_generated_mcp_entry_token>"

guanbi-mcp-server-controller.yaml

kind: Deployment
apiVersion: apps/v1
metadata:
  name: guanbi-mcp-server-controller
spec:
  replicas: 1
  selector:
    matchLabels:
      app: guanbi-mcp-server
  template:
    metadata:
      labels:
        app: guanbi-mcp-server
    spec:
      imagePullSecrets:
        - name: gd-cr-registry
      containers:
        - name: guanbi-mcp-server
          image: guandata-registry.cn-hangzhou.cr.aliyuncs.com/guandata/guanbi-mcp-server:0.1.14
          imagePullPolicy: IfNotPresent
          envFrom:
            - configMapRef:
                name: guanbi-mcp-server
          env:
            - name: TZ
              value: Asia/Shanghai
            - name: MCP_ENTRYPOINT_TOKEN
              valueFrom:
                secretKeyRef:
                  name: guanbi-mcp-server
                  key: MCP_ENTRYPOINT_TOKEN
                  optional: false
          ports:
            - name: http
              containerPort: 9090
          livenessProbe:
            httpGet:
              path: /sysmon/health/liveness
              port: 9090
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /sysmon/health/readiness
              port: 9090
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          resources:
            requests:
              cpu: 100m
              memory: 256Mi
            limits:
              cpu: 1000m
              memory: 1Gi

Replace image with the actual image address and version for the customer environment. If the customer uses a private registry, confirm image pull credentials are configured.

guanbi-mcp-server-service.yaml

kind: Service
apiVersion: v1
metadata:
  name: guanbi-mcp-server
spec:
  type: ClusterIP
  ports:
    - name: http
      port: 9090
      targetPort: 9090
  selector:
    app: guanbi-mcp-server

This example uses ClusterIP. To expose the service externally, configure Ingress, gateway, or another exposure method according to the customer environment.

Deployment Steps

kubectl apply -f guanbi-mcp-server-configmap.yaml
kubectl apply -f guanbi-mcp-server-secret.yaml
kubectl apply -f guanbi-mcp-server-controller.yaml
kubectl apply -f guanbi-mcp-server-service.yaml

Check Pod and Service status:

kubectl get pod -l app=guanbi-mcp-server
kubectl get svc guanbi-mcp-server

View startup logs:

kubectl logs -l app=guanbi-mcp-server --tail=200

If the customer cluster uses a non-default namespace, add -n <namespace> to all kubectl apply and check commands.

Feishu Aily Integration

To connect Feishu Aily, add configuration to ConfigMap, Secret, and Deployment on top of the base deployment.

User Identity Passed by Aily

Aily passes user identity in Headers:

Header	Meaning	Recommendation
`x-aily-user`	User `Feishu_user_id` in the enterprise, usually a numeric string.	This is not the employee ID and is hard to obtain, so it is not recommended first.
`x-aily-email`	Current user's email.	Recommended for matching GuanBI user email and troubleshooting.

Production should use x-aily-email to identify users. See Feishu Aily MCP configuration documentation.

Modify ConfigMap

Add to data in guanbi-mcp-server-configmap.yaml:

BI_LOGIN_ID_HEADER: ""
BI_USER_PROPERTY_HEADER: "x-aily-email"
BI_USER_PROPERTY_KEY: "email"

This means: read current-user email from Aily request Header x-aily-email, then match the unique GuanBI user by the email user property.

If the customer wants to use Feishu_user_id and GuanBI user properties already maintain the value, use:

BI_LOGIN_ID_HEADER: ""
BI_USER_PROPERTY_HEADER: "x-aily-user"
BI_USER_PROPERTY_KEY: "<GuanBI_user_property_key_for_Feishu_user_id>"

Obtain Account Synchronization Token

Before deployment, obtain the account synchronization token from the corresponding Guandata BI page. This token maps external accounts to GuanBI users and is configured as BI_APP_TOKEN in MCP Server.

This token is sensitive and must be written to Secret, not ConfigMap.

Modify Secret

apiVersion: v1
kind: Secret
metadata:
  name: guanbi-mcp-server
type: Opaque
stringData:
  MCP_ENTRYPOINT_TOKEN: "<previous_mcp_entry_token>"
  BI_APP_TOKEN: "<account_synchronization_token>"

Modify Deployment

Add BI_APP_TOKEN to env in guanbi-mcp-server-controller.yaml:

            - name: BI_APP_TOKEN
              valueFrom:
                secretKeyRef:
                  name: guanbi-mcp-server
                  key: BI_APP_TOKEN
                  optional: true

Apply again:

kubectl apply -f guanbi-mcp-server-configmap.yaml
kubectl apply -f guanbi-mcp-server-secret.yaml
kubectl apply -f guanbi-mcp-server-controller.yaml

After deployment, provide Aily configuration owners with:

Full MCP Server URL, preferably ending with /mcp, such as https://guanbi-mcp.example.com/mcp.
MCP_ENTRYPOINT_TOKEN, used in Aily header Authorization: Bearer <MCP_ENTRYPOINT_TOKEN>.

Client Integration

HTTP Client

Call the MCP entry:

POST https://guanbi-mcp.example.com/mcp

If trusted gateway is not enabled, include:

Authorization: Bearer <mcp_service_token>

Then pass the current real user identity according to the identity solution:

Identity Method	Request Carries	Scenario
Direct uIdToken	`X-GuanBI-Uid-Token: <current_user_uid_token>`	Upstream already has GuanBI user token.
loginId exchange	`X-GuanBI-Login-Id: <current_user_login_id>`	Upstream can confirm GuanBI loginId.
External account mapping	`<external-user-header>: <external_user_id>`	Upstream only has external IDs such as Feishu account.

Prefer gateway-injected identity headers and drop same-name headers from external requests.

Feishu Aily Client

For Aily, use external account mapping. Aily only needs MCP service URL and entry credential:

Client Configuration	Description
MCP service URL	Example: `https://guanbi-mcp.example.com/mcp`.
`Authorization`	`Bearer <mcp_service_token>`, matching server `MCP_ENTRYPOINT_TOKEN`.

Aily automatically includes user identifiers, commonly x-aily-user and x-aily-email. Production should map GuanBI users by x-aily-email. Do not configure BI token, loginId, or BI_APP_TOKEN on the client side.

Important

Every time MCP Server is upgraded or configuration is changed, open the target MCP edit page in Aily MCP Marketplace and save once to refresh MCP configuration.

Key Configuration

Configuration	Description
`BI_BASE_URL`	Required. BI site accessed by the current MCP service.
`BI_PUBLIC_PATH`	Required. Use `/` when there is no prefix; use the corresponding prefix such as `/guanbi` when deployed under a sub-path.
`MCP_TRANSPORT`	`stdio` or `streamable-http`.
`BI_UID_TOKEN`	Local user token for `stdio`.
`BI_LOGIN_DOMAIN` / `BI_LOGIN_ID` / `BI_LOGIN_PASSWORD`	Local account/password login for `stdio`.
`MCP_ENTRYPOINT_TOKEN`	HTTP entry credential. Store it in Secret.
`MCP_TRUSTED_GATEWAY`	When set to `true`, `MCP_ENTRYPOINT_TOKEN` is not required. Enable only when a trusted gateway already authenticates and injects identity.
`BI_APP_TOKEN`	Server-side key for identity exchange. Must be stored in Secret. Not needed for base deployment.
`BI_LOGIN_ID_HEADER`	loginId identity header. Default: `x-guanbi-login-id`.
`BI_USER_PROPERTY_HEADER` / `BI_USER_PROPERTY_KEY`	Used when mapping external accounts to BI users.
`BI_MAX_ROWS`	SQL row limit. Default: `1000`.
`GUANBI_MCP_USAGE_STATS`	Set to `0`, `false`, `off`, or `no` to disable anonymous statistics.

Permissions and Security Boundaries

MCP entry credentials only prove that the caller can access MCP, not that the caller can view BI data.
BI data permissions are determined by GuanBI according to the current user identity.
HTTP mode must resolve the current real user on every request. Do not query for all users through a process-level fixed user.
x-tenant-id, x-end-user-id, and x-trace-id are for observability only and cannot replace BI authorization.
BI_APP_TOKEN must be stored on the server and must not be passed from clients.
Identity exchange debug is only for temporary troubleshooting and should be disabled afterward.
GuanMCP only reports aggregated tool-call statistics by default. It does not collect questions, SQL, tokens, returned content, or user identity.

Launch Acceptance

Before launch, check:

Health checks are normal.
get_bi_capabilities can show BI site, run mode, and tool list.
Low-permission users can only access BI resources they are allowed to access.
HTTP requests without entry credentials are rejected unless trusted gateway is enabled.
In Aily, the client only configures Authorization; user ID is passed automatically and maps to a unique BI user.
Card flow works: search resource -> read card information -> read data in read-only mode.
Metric flow works: search metric -> read definition -> query data.
ChatBI flow works: list topics -> ask question -> view result.
SQL flow confirms BI version and Advanced SQL switch; table names use dataset display names.

Use at least two accounts for acceptance: one high-permission account and one regular business account. The same question should return scopes consistent with each user's BI permissions.

Common Misunderstandings

Tool visibility does not mean the user has resource permission.
BI_APP_TOKEN must not be passed by clients; it is stored only on the server.
Normal card queries read saved results in read-only mode and do not modify cards.
SQL query is not always available by default. It depends on BI capabilities and switches.

Notes

BI_BASE_URL must be the actual BI address accessible by the customer.
BI_PUBLIC_PATH must match the customer's BI access prefix; use / when there is no prefix.
MCP_ENTRYPOINT_TOKEN and BI_APP_TOKEN are sensitive and must be managed through Secret. Do not write them in plaintext YAML, repositories, or public documents.
BI_APP_TOKEN is only required for account synchronization or external account mapping. It is not required for base deployment.
The example image version is 0.1.14; confirm the image tag before deployment if a specific version is required.
The example Service type is ClusterIP. To expose externally, configure Ingress, gateway, or another method based on the customer environment.
If the customer cluster namespace is not default, add -n <namespace> to all kubectl apply and check commands.

Deployment Overview​

Roles and Responsibilities Before Deployment​

Local stdio Deployment​

Login Methods​

Client Configuration Example​

Production HTTP Deployment​

Key Endpoints​

Routing Suggestions​

Prepare Before Deployment​

Confirm BI Access URL​

Generate MCP Entry Token​

Kubernetes Configuration Files​

guanbi-mcp-server-configmap.yaml​

guanbi-mcp-server-secret.yaml​

guanbi-mcp-server-controller.yaml​

guanbi-mcp-server-service.yaml​

Deployment Steps​

Feishu Aily Integration​

User Identity Passed by Aily​

Modify ConfigMap​

Obtain Account Synchronization Token​

Modify Secret​

Modify Deployment​

Client Integration​

HTTP Client​

Feishu Aily Client​

Key Configuration​

Permissions and Security Boundaries​

Launch Acceptance​

Common Misunderstandings​

Notes​