# Helix AI Access Handbook > A company-wide guide: what MCP / CLI / plugins / connectors are, how to use > them, how to pick between them — and, if your team wants to bring the same > capabilities to your own system, how to build it to the same production-grade > standard as Helix. > > This is the knowledge-base source document, maintained in the Helix repo under > `docs/kb/`; a condensed in-product version is always available in Helix under > Help Center → AI 助手集成 (AI Assistant Integration). --- # Part 1 · Concepts and Usage (no background required) ## 1. All the jargon in one sentence each Imagine having an IT colleague who knows everything. You used to log into systems yourself, click through menus, and fill in forms; now you can simply tell an AI "which laptop is mine?" or "request a Zoom seat for me," and the AI deals with the systems on your behalf. Making that possible takes a few pieces working together: | Term | One-sentence explanation | Everyday analogy | |------|--------------------------|------------------| | **MCP** | The "standard interface protocol" that lets an AI call a system | The USB-C port on an appliance: any brand of cable plugs in | | **MCP Server** | The set of capabilities a system exposes following the MCP standard | The USB-C port on the Helix "appliance" | | **Tool** | One specific capability inside an MCP Server | "Look up my assets" and "submit a request" are each a tool | | **Connector** | Adding an MCP Server in claude.ai / Claude Desktop | Plugging in the cable and signing in | | **Plugin** | A one-command install package for Claude Code (Claude in the terminal) | Installing a phone app: connection + playbooks + shortcuts, all at once | | **CLI** | A command-line tool that calls the system directly from the terminal, no AI involved | A remote control: press the buttons yourself, no need to talk to the AI | | **PAT (personal access token)** | A secret string that represents "you personally," for scripts/clients | A key that opens only your own drawer | | **OAuth** | Signing in and authorizing in the browser, no key-copying required | Walking in with face recognition — no key needed | **Why MCP matters**: it is a vendor-neutral industry standard (initiated by Anthropic; OpenAI, Cursor, and others already support it). Helix built exactly one MCP Server, and every MCP-capable AI client can use it — no per-client development required. ## 2. The security model: three reassurances up front No matter which path you connect through, these three iron rules are identical: 1. **The AI only ever gets *your* permissions** — anything you cannot see in the web UI, the AI cannot see either. An admin's AI can do admin things; a regular employee's AI cannot. 2. **Write operations still go through approval** — when the AI says "request submitted," it means it clicked "Submit" on your behalf. The approval chain (Feishu approval to IT / asset admins) is not shortened by a single step. The AI is not a backdoor around governance. 3. **Every step is audited** — every AI call is recorded in the audit log (action, time, token, IP), and all access is automatically revoked when someone leaves the company. ## 3. Which path should I use? (six-path decision) Ordered from broadest audience to narrowest — go down the list and stop at the first row that fits you: | Who you are | Which path | What to do | |-------------|------------|------------| | Everyone, no setup wanted | **Helix in-product AI assistant** | Open the Helix web app and ask in the bottom-right corner | | claude.ai web / Claude Desktop users | **Claude connector (OAuth)** | Paste one URL, sign in once in the browser | | Engineers using the Claude Code terminal | **Claude Code plugin** | One command: `helix plugin install` | | Writing scripts, running automation | **helix CLI** | Download from the Help Center, configure a PAT once | | Cursor and other MCP clients | **Direct MCP connection** | Paste the same endpoint URL | | Teams building system-to-system integrations | **External API (helix_api_)** | Request machine credentials, authorized by scope | > Remember: the choice only changes the **entry point**, never the > **permissions**. ## 4. Step by step: connecting via the four main paths ### 4.1 Claude connector (zero install, recommended for most people) 1. Open claude.ai (or Claude Desktop) → Settings → Connectors → **Add custom connector** 2. For the URL, enter `https://helix.pingcap.net/api/v1/mcp` and choose **Individual sign-in** as the connection method 3. The browser redirects to Helix sign-in (Google/Feishu) → a consent page appears → click "Authorize" 4. Done. Try asking: "Use helix to show me the devices registered to me" No token needs to be created; to revoke access later, go to Helix "Settings → Connected apps" and disconnect with one click. ### 4.2 Claude Code plugin (engineers) If you already have the helix CLI installed (recommended): ```bash helix plugin install # download + verify + auto-register with Claude Code ``` If you don't have the CLI: Help Center → AI Assistant Integration → Claude Code plugin → download the zip, extract it, then: ```bash unzip ~/Downloads/helix-claude-plugin.zip -d ~/.helix/ claude plugin marketplace add ~/.helix/helix-claude-plugin claude plugin install helix@helix ``` > The path must start with `~/`, `./` or `/`. If you hit > `SSH authentication failed / Permission denied (publickey)`, the leading > `~/.` got dropped — claude treated `helix/helix-claude-plugin` as a GitHub > repo to clone. It is not a local file-permission problem; rerun with the > full path. After installing you get: the Helix MCP connection (a browser SSO prompt on first use, zero tokens), a set of playbook skills (the AI automatically knows how to combine 400+ tools), and five slash commands: `/helix:whoami`, `/helix:my-it`, `/helix:approvals`, `/helix:costs`, `/helix:support`. To update: `helix plugin update`. ### 4.3 helix CLI (scripts and automation) 1. Help Center → AI Assistant Integration → helix CLI: download the single-file binary for your OS (no Python required) 2. Use "Create PAT in one click" to get a token, then: ```bash helix config set-url https://helix.pingcap.net pbpaste | helix auth token set --token-stdin # read from clipboard, never shell history helix whoami # verify helix mcp call list_my_assets --arg page=1 # call any tool ``` Exit-code contract (scriptable): 0 success / 1 usage error / 2 unauthenticated / 3 forbidden / 4 rejected by remote / 5 network error. For dangerous operations (such as `server_destroy`) the CLI enforces a second confirmation; only `--yes` skips it. ### 4.4 Other MCP clients (Cursor, etc.) Paste the same endpoint `https://helix.pingcap.net/api/v1/mcp`: clients that support OAuth (including Cursor) will automatically walk you through browser sign-in; for clients that don't, set the request header `Authorization: Bearer helix_pat_…`. ## 5. What the AI can do for you (examples) - **Look things up**: "What hardware do I have?" "Which cloud servers do I have in ap-northeast-1?" "Which approvals are still pending?" "Which of my domains are about to expire?" "What's my IT cost this month?" - **Get things done (through approval)**: "Request a Zoom seat; the reason is a customer demo" "Add a sales-china@ alias to my mailbox" "Borrow asset HX-LP-0042, returning June 1" - **Official playbooks (Prompts)**: pick them directly in supported clients — My IT overview / Approvals at a glance / Cost check-up / Offboarding handover checklist / Onboarding progress. --- # Part 2 · Building Guide (for teams who want to do the same) > Intended readers: engineering teams that want to add the same AI > capabilities to their own systems (expenses, CRM, ticketing, data > platforms, …). Helix's implementation is fully open in the company repo and > can be copied directly. ## 6. Overall architecture: one center, many entry points ``` ┌────────────────────────────┐ claude.ai / Desktop ───▶│ │ Claude Code plugin ────▶│ your system's MCP server │──▶ business logic Cursor & other clients ▶│ (auth/audit/approvals here)│ │ CLI (mcp call) ────────▶│ │ database └────────────────────────────┘ ``` **Core principle: build every capability exactly once.** The MCP Server is the single center of capability; the plugin, CLI, and connectors are only thin entry shells around it. The Helix CLI reimplements zero business logic — `helix assets list` is internally just `mcp call list_my_assets`. ## 7. Ten hard rules for a production-grade MCP Server Every rule below has real Helix code to reference (all paths are in the Helix repo): 1. **Identity travels with the request; permissions travel with the person** — every tool call resolves "which employee is this," reusing the system's existing RBAC. Never build a separate permission set just for the AI. See `server/app/mcp/middleware.py` (dual PAT/OAuth channels) + `runtime.py` (roles fetched fresh from the DB on every request). 2. **Dual auth: PAT for config files, OAuth for GUIs** — GUI connectors (claude.ai) only accept OAuth discovery (RFC 9728/8414/7591/7636): short-lived access tokens + audience binding, single-use refresh rotation. See `server/app/auth/oauth/`. 3. **Write operations go through the existing approval chain** — mutating tools merely "submit on the user's behalf"; never let the AI write to the database directly. Every Helix write tool goes into Feishu approval or the idempotent task queue. 4. **Audit everything** — every call logs `action="mcp."` + trace_id + token ID. 5. **Automate tool annotations** — don't hand-write a 400-row table of `readOnlyHint`/`destructiveHint`; derive them from the read/write source of truth in the code (Helix uses AST parsing at startup, see `server/app/mcp/annotations.py`); lock the danger list and the CLI confirmation list with tests. 6. **Write descriptions for the AI** — a tool description should explain "when to use me, how to fill the parameters, what I return, and how I differ from neighboring tools," and map 1:1 to the HTTP endpoint. 7. **Don't skip Resources and Prompts** — publish the platform's self-description and a live tool catalog as Resources; package high- frequency workflows as official Prompts shared across all clients (see `resources.py`/`prompts.py`). 8. **Idempotency + rate limiting + version gate** — writes are idempotent; rate-limit per user; clients carry their version in the UA, and the server can set a minimum-version kill switch (see `CLI_MIN_SUPPORTED_VERSION`). 9. **Leaving means losing access** — tokens/grants are all attached to a person and revoked uniformly by the offboarding flow; writes have the Leaver gate as an additional backstop. 10. **Lock contracts with tests** — the tool-count hint, full annotation coverage, danger-list consistency, and auth 401/403 all have regression tests (see `server/tests/test_mcp*`). ## 8. CLI: a thin shell over MCP, not a second backend - Depends only on an HTTP client + the standard library, and can be packaged as a single-file binary for distribution (PyInstaller) - Every business command = `mcp call `; convenience commands are just aliases - Copy the security details verbatim: tokens are read only from stdin/env/config file (never accept a `--token` argument), all secrets are masked in output, `https://` is enforced, dangerous tools require a second TTY confirmation - Distribution: CI build → S3 fixed namespace + `latest/manifest.json` → in-product download card (presigned URL + sha256 display). See `.github/workflows/cli-release.yml` + `server/app/domains/cli_dist/` ## 9. Claude Code plugin: packaging and distribution - Structure: a marketplace directory (`.claude-plugin/marketplace.json`) wrapping the plugin directory (`.claude-plugin/plugin.json` + `.mcp.json` + `skills/` + `commands/`) - **Zero credentials in `.mcp.json`**: no Authorization header — let the client go through OAuth discovery; use `${VAR:-default}` to support local dev overrides - Skills describe "how to combine tools to get things done," not a restated tool list; tool names must match the registered surface exactly (run validation before shipping) - **Distribution pitfall (learned the hard way)**: when marketplace.json is served directly from an HTTPS URL, relative-path plugin sources do not resolve — external sources must be git/npm. For intranet scenarios, zip the whole directory into object storage and have employees register a local directory; pair it with ` plugin install/update` as the installer (sha256 verification + zip-slip protection + atomic swap into a fixed path). See Helix `plugin/` + DECISIONS 2026-07-09 - **Do not build an MCPB (Claude Desktop extension bundle)**: it only supports local stdio; forcing a remote HTTP system into it means bundling a local bridge + long-lived tokens — strictly worse than an OAuth connector ## 10. Engineering-side companion setup (team productivity, not a platform-facing capability) - **CLAUDE.md / AGENTS.md**: put an "AI onboarding manual" at the repo root — architecture map, non-negotiable rules, verification commands, doc-update discipline. Helix's `CLAUDE.md` is a model to copy; the key lesson: make the AI "check for existing capabilities before building" (Helix once nearly rebuilt an OAuth service that was already live). - **Hooks / Subagents / slash commands**: Claude Code's project-level extension points, living in the `.claude/` directory; good for enforcing coding standards, dedicated review agents, and shortcuts for common operations. - **GitHub Action**: the pattern of bringing @claude into PRs for review/fixes, suited to the CI side. - **Agent SDK**: when you want to embed an AI assistant into your own product UI (like the Helix in-product copilot), build it with the Agent SDK — it connects to the same MCP underneath. ## 11. Security and governance checklist (mandatory questions for the enterprise) - [ ] AI-channel permissions == web permissions (no separate privilege-escalation surface) - [ ] Write operations go 100% through the approval chain; dangerous tools carry client confirmation annotations + CLI double confirmation - [ ] Full audit with trace_id; from a token you can trace back to the person/IP/action - [ ] OAuth: PKCE + short-lived tokens + audience binding + refresh rotation; PAT: recognizable prefix, expiry, one per device, last-used visible, individually revocable - [ ] Automatic invalidation on offboarding (three layers: tokens + OAuth grants + write gate) - [ ] Prompt-injection awareness: tool descriptions/resource content are an "instruction surface for the AI" — review them before shipping; never put dynamic content that external data could poison into descriptions - [ ] Confused deputy: the server validates the permissions of the **token owner**, and never trusts the identity a client claims for itself - [ ] Distribution integrity: artifacts ship with sha256 and the installer verifies it; marketplace/zip contents get structural validation to block poisoning - [ ] Version kill switch: on discovering a vulnerability, you can force everyone to upgrade - [ ] Register new capabilities: after standing up a new MCP Server, register it in the IT knowledge base (name/endpoint/owner/scopes) and report it to Helix IT for inclusion in the connector allowlist ## 12. One-page quick reference | What you want to build | Where to copy from | |------------------------|--------------------| | MCP Server auth/audit/runtime | `server/app/mcp/{middleware,runtime}.py` | | OAuth authorization service | `server/app/auth/oauth/` | | Automatic tool-annotation derivation | `server/app/mcp/annotations.py` | | Resources / Prompts | `server/app/mcp/{resources,prompts}.py` | | CLI skeleton and security details | `cli/helix_cli/` | | CLI/plugin S3 distribution pipeline | `.github/workflows/{cli,plugin}-release.yml` | | In-product download card / help pages | `web/src/pages/help/` | | The plugin itself | `plugin/marketplace/` | | Decision rationale (why it's built this way) | `docs/architecture/DECISIONS.md` 2026-06-18/23, 2026-07-09 | --- *Maintained by: IT — Helix Platform. Condensed in-product version: Helix → Help Center → AI Assistant Integration.* *This document evolves with the platform; if you find outdated content, file a ticket or edit the repo source directly.*