---
name: using-helix
description: >-
  Core conventions for talking to the Helix MCP server (PingCAP's unified
  IT platform). Load this whenever any Helix tool is about to be used —
  before assets, approvals, cloud, software-seat, onboarding or cost
  questions — to apply the platform's permission, approval-chain and
  pagination semantics correctly. Triggers: any mention of Helix, 内部IT,
  我的设备/资产/审批/席位/云资源, or a helix-prefixed MCP tool.
---

# Using Helix from Claude

Helix is PingCAP's unified IT platform (people, hardware assets, software
seats, cloud resources, approvals, onboarding/offboarding). The MCP server
exposes 400+ tools. These conventions apply to ALL of them.

## Identity & permissions

- Every tool call runs **as the signed-in user** (OAuth or personal access
  token). Results are scoped to exactly what that user can see in the
  Helix web UI — same RBAC, same manager-derived scope.
- An empty result often means "not visible to you", not "does not exist".
  Say so: "你的权限范围内没有…" rather than "系统里没有…".
- To check who you are acting as (and which roles apply), call
  `get_my_profile` once at the start of a session that involves
  permission-sensitive questions. Do not repeat it per call.

## Writes go through the approval chain

- Mutating tools **submit** the same request a web-UI click would; they
  do not bypass review. A "success" response usually means *request
  created*, not *action completed*. Report it that way and, where the
  tool returns a request/approval id, offer to track it with
  `list_my_approval_requests`.
- Never present a submitted request as a finished state change.
- Some actions are gated to admin roles; a `403`/permission error is a
  normal outcome for a regular employee — explain which role is needed
  instead of retrying.

## Pagination & list hygiene

- List tools accept `page` / `page_size`. Use `page_size` ≤ 50 and read
  `meta.pagination.total` (or the tool's `total` field) before deciding
  to fetch more pages. Never loop past 3 pages without telling the user
  how many results exist and asking whether to continue.

## Masked data

- Contact fields come masked (`mobile_phone_masked`,
  `personal_email_masked`). There is a separate step-up reveal flow —
  do not try to reconstruct masked values.

## Language

- Answer in the user's language. The workforce is bilingual (zh-CN
  primary, en-US common, some ja-JP). Keep Helix enum values (`active`,
  `pending_approval`, …) verbatim in code font and translate their
  meaning in prose.

## Error semantics

- `401` → the session/token expired or was revoked: tell the user to
  re-authenticate (`/mcp` in Claude Code re-runs the OAuth flow).
- `403` → role/permission gate; name the missing role if the message
  includes it.
- `404` on a resource the user "owns" → usually a scope boundary, not a
  data-loss event.
- `429` → the per-user rate window; wait briefly rather than retrying in
  a tight loop.

## Choosing between overlapping tools

- Prefer purpose-built aggregates (`get_my_loadout`,
  `get_my_it_footprint`, `get_dashboard_summary`) over stitching many
  narrow list calls when the user asks a broad "what do I have" /
  "总览" question — they're cheaper and pre-scoped.
- For anything money-related, prefer the `finance_*` / `cost_*` families
  over inferring from raw lists.