{
  "markdown": "# BailingHub MCP Server\n\n[简体中文](README.zh-CN.md) | English\n\nLet an MCP-compatible AI agent use natural-language requests to query and operate your\nstore, SaaS, CRM, ERP, or other business system through\n[BailingHub](https://www.bailinghub.com/).\n\nDepending on the capabilities explicitly exposed by the business system and the routes\nallowed for this connection, an agent can, for example:\n\n- find products with fewer than 10 items in stock and prepare a restocking suggestion;\n- update an employee or customer profile;\n- submit a refund request and wait when the configured route requires human approval.\n\nThe agent does not receive administrator or business-system credentials. BailingHub keeps\nthe route boundary, approval state, execution record, and audit trail, while the downstream\nbusiness system still makes the final authorization decision.\n\n> **0.3.0:** adds host-controlled multi-connection lifecycle APIs and CurrentUser DPAPI storage\n> for Windows Agent Sessions. The existing Agent Client and `0.1.x` Client Token behavior remains\n> compatible and is not replaced.\n\nThis package is a thin integration adapter. It does not embed BailingHub, grant business\npermissions, or replace the downstream business system's final authorization. It supports\nboth the existing operator-provisioned Client Token mode and an Agent Session mode in\nwhich a human approves one local Agent through the system browser.\n\n## What It Exposes\n\n| Tool | Purpose |\n| --- | --- |\n| `submit_governed_job` | Submit untrusted task text to one operator-configured BailingHub route |\n| `get_governed_job` | Read the current public state of a credential-owned job |\n| `wait_for_governed_job` | Poll one job for at most 60 seconds without resubmitting it |\n\nThe Agent Client 0.3 path starts with five small meta-tools for turn bootstrap,\ncapability search, governed invocation/recovery, and visible run completion. BailingHub then\nreturns at most 12 active business tools for the current turn; each replacement removes the\nprevious active set instead of growing the model context indefinitely.\n\nHost implementers should use the [host-neutral Agent Client SDK guide](docs/AGENT_CLIENT_SDK.md).\n\nThe route, BailingHub URL, and credential are local process configuration. They are never\nMCP tool arguments and therefore cannot be selected or replaced by model output.\n\n## Authentication Modes\n\n- **Agent Session:** run `bailinghub-mcp-server login` once. The CLI uses a random loopback\n  callback plus PKCE, opens the system browser, and stores the approved session in the\n  platform-specific secure credential store. The MCP tools then use `/agent-api/v1/*` and\n  refresh rotated tokens locally.\n- **Client Token (compatible):** when `BAILINGHUB_CLIENT_TOKEN` is present, the adapter keeps\n  using `POST /run` and `GET /jobs/{job_id}` exactly as before.\n\nNeither mode lets the model supply a credential, route, acting subject, or approval result.\nThe Agent Session records the identity approved by the Hub/business authorization boundary;\nthe downstream business system still makes the final authorization decision.\n\nThe MCP Registry `server.json` describes only the compatible standalone stdio/Client Token\ninstallation, so that entry still marks `BAILINGHUB_CLIENT_TOKEN` as required. The native DSH\nplugin does not consume that Registry configuration: it imports this package's `/sdk` subpath as\nan ordinary library dependency and establishes an Agent Session through the browser. Do not add a\nClient Token field to a DSH plugin based on the Registry form.\n\n## Security Model\n\n```text\nMCP host / model\n    |\n    | request_id + untrusted input\n    v\nBailingHub MCP Server\n    |\n    | fixed route + Client Token or approved Agent Session\n    v\nBailingHub\n    |\n    | governed dispatch\n    v\nBusiness system\n    |\n    +-- resolves trusted subject and performs final authorization\n```\n\nThe adapter intentionally does not accept:\n\n- an acting subject or identity claim;\n- a Client Token, administrator token, or business-system credential as tool input;\n- an approval decision or approval evidence;\n- an executor identity;\n- arbitrary metadata or callback URLs;\n- an arbitrary route.\n\nIn compatible Client Token mode, use a dedicated token restricted to the one route configured\nfor this server process. Run separate server instances when different MCP clients need\ndifferent route boundaries.\n\n## Install\n\nPrerequisites:\n\n- Node.js 20.15 or newer;\n- a reachable BailingHub deployment;\n- either one route-scoped BailingHub Client Token or a registered public Agent client that\n  can be approved for the required route.\n\nFor the legacy static-job mode, configure an MCP host to spawn:\n\n```json\n{\n  \"mcpServers\": {\n    \"bailinghub\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"bailinghub-mcp-server\"],\n      \"env\": {\n        \"BAILINGHUB_BASE_URL\": \"https://hub.example.com\",\n        \"BAILINGHUB_CLIENT_TOKEN\": \"replace-with-a-route-scoped-client-token\",\n        \"BAILINGHUB_ROUTE\": \"order_assistant\"\n      }\n    }\n  }\n}\n```\n\n### Agent Session login\n\nAuthorize one registered public Agent client and one fixed route before starting the MCP\nhost without a Client Token:\n\n```bash\nbailinghub-mcp-server login \\\n  --base-url https://hub.example.com \\\n  --client-app-id merchant-agent \\\n  --route order-assistant\n\nbailinghub-mcp-server status\nbailinghub-mcp-server logout\n```\n\nThe login callback binds only to a random `127.0.0.1` port and uses `state` plus PKCE S256.\nAccess and refresh tokens never appear in CLI output. macOS uses Keychain. Linux and other\nPOSIX platforms require an explicit `BAILINGHUB_ALLOW_FILE_CREDENTIAL_STORE=true` opt-in;\nthat fallback rejects files that are not owned by the current user with mode `0600`.\nWindows uses a CurrentUser DPAPI-protected file under the user's LocalAppData directory. If\nWindows PowerShell or DPAPI is unavailable, Agent Session fails closed and never falls back to\nplaintext. Compatible Client Token mode remains available on every supported platform.\n\nFor a local BailingHub process, loopback HTTP is accepted:\n\n```text\nBAILINGHUB_BASE_URL=http://127.0.0.1:3000\n```\n\nNon-loopback HTTP is rejected by default. `BAILINGHUB_ALLOW_INSECURE_HTTP=true` exists only\nfor an operator-controlled private network where TLS terminates elsewhere. Do not use it\nacross an untrusted network.\n\n## Correct Job Flow\n\n1. Create a stable `request_id` for one business request.\n2. Call `submit_governed_job` with that ID and the task text.\n3. Preserve the returned `job_id`.\n4. Call `wait_for_governed_job` for a short bounded wait, or call `get_governed_job` later.\n5. If submission must be retried, reuse the exact same `request_id` and task meaning.\n\n`queued`, `running`, and `dispatched` are non-terminal. `done`, `error`, and `rejected` are\nterminal. A wait timeout is not a failed task and must not cause a replacement submission.\n\n## First Success and Feedback\n\nUse the [MCP integration path](https://www.bailinghub.com/en/integrations#mcp) as the\ncanonical start page. The first integration is successful when an MCP host submits through\nthe operator-fixed route, the same `job_id` reaches a terminal state, BailingHub retains\nits approval and audit state, and the MCP host never receives administrator or\nbusiness-system credentials.\n\nReport a PASS, partial result, or failure through the\n[BailingHub independent validation form](https://github.com/bailinghub/bailinghub/issues/new?template=independent_validation.yml)\nand select the MCP track. Never include tokens, model keys, personal information, or\nproduction business data.\n\n## Project Boundaries\n\nThe dependency direction is one-way:\n\n```text\nbailinghub-mcp-server -> BailingHub public Client API / Agent API\nBailingHub may consume ACC declarations\nACC has no dependency on either implementation\n```\n\nSee:\n\n- [Project boundaries](docs/PROJECT_BOUNDARIES.md)\n- [Threat model](docs/THREAT_MODEL.md)\n- [Compatibility contract](docs/COMPATIBILITY.md)\n- [Agent Client SDK](docs/AGENT_CLIENT_SDK.md)\n- [Privacy](PRIVACY.md)\n- [Security policy](SECURITY.md)\n\n## Development\n\n```bash\nnpm install\nnpm run verify\nnpm pack --dry-run\n```\n\nClient Token mode uses the stable `bailing.client-api.v1` surface:\n\n- `POST /run`\n- `GET /jobs/{job_id}`\n\nAgent Session mode uses the additive Agent Auth v1 and Agent API v1 surfaces:\n\n- `POST /agent-auth/v1/authorizations`\n- `POST /agent-auth/v1/token`\n- `GET /agent-auth/v1/session`\n- `POST /agent-auth/v1/revoke`\n- `GET /agent-api/v1/workspaces`\n- `GET /agent-api/v1/workspaces/{route}/bootstrap`\n- `POST /agent-api/v1/workspaces/{route}/turns`\n- `POST /agent-api/v1/workspaces/{route}/capabilities/search`\n- `POST /agent-api/v1/tool-invocations`\n- `POST /agent-api/v1/tool-invocations/{invocation_id}/resume`\n- `POST /agent-api/v1/runs/{run_id}/complete`\n\nThe `bailinghub-mcp-server/sdk` subpath additionally exposes a host-neutral Agent Client factory.\nIt owns browser login, named local selectors, isolated credentials, token refresh, and Core DTO\nmapping. On the same Hub/client/workspace binding it replaces an older local connection only when\nCore reports the same trusted `on_behalf_of`; different business identities remain independently\nselectable. Core resolves the business authorization entry, so host adapters such as DSH never ask\nfor a business URL and do not own credentials or BailingHub HTTP endpoint details.\n\nNo administrator, executor, approval-decision, tool-proxy, configuration, or direct business\nAPI is called by this adapter.\n",
  "bytes": 9458,
  "sha": "ea339c97c8816b932223ae3ec20b3865cd81bd96834146df8fa3eddc1c035969",
  "repo_slug": "bailinghub/bailinghub-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bailinghub_bailinghub_governan_c3365ccc/readme"
}