bailinghub-mcp-server
OfficialThis server lets an MCP agent submit and monitor governed business-system tasks through a fixed BailingHub route, without handling credentials or final authorization.
Submit a governed job: Send untrusted natural-language task text with a stable
request_id; retries reuse the same ID for idempotency.Read job state: Fetch the public status and result of a job owned by this client using its
job_id.Wait briefly for completion: Poll one job for 1–60 seconds; a timeout returns the latest state and does not resubmit the action.
Stay within governance: The route, credentials, acting subject, approval decisions, and final business authorization remain outside model control; BailingHub applies configured reach, risk, approval, rate-limit, and audit controls.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bailinghub-mcp-server Submit a governed job to approve refund for order 456"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
BailingHub MCP Server
0.8.0: larger tool inputs and knowledge on demand
Save complete page content without a small adapter limit, read only the relevant business guidance, and choose model defaults independently of service ceilings. Pair Core 0.10.0 / SDK 0.8.0 / DSH 0.8.0. Existing authorization, approval and original-operation recovery remain in force; automatic task continuation is a host responsibility.
简体中文 | English
Let an MCP-compatible AI agent use natural-language requests to query and operate your store, SaaS, CRM, ERP, or other business system through BailingHub.
Depending on the capabilities explicitly exposed by the business system and the routes allowed for this connection, an agent can, for example:
find products with fewer than 10 items in stock and prepare a restocking suggestion;
update an employee or customer profile;
submit a refund request and wait when the configured route requires human approval.
The agent does not receive administrator or business-system credentials. BailingHub keeps the route boundary, approval state, execution record, and audit trail, while the downstream business system still makes the final authorization decision.
Related MCP server: BailingHub MCP Server
Previously introduced in 0.5.0: shop and inventory in one conversation
A host can let a user ask: “Check tumbler stock; if available, change the corresponding shop product to 59 and list it.” This SDK adds original-target checks for different systems on one Hub, system descriptions before tool search, and business-supplied authorization names. Actions must be exposed by the business systems, product mappings confirmed, and original approvals respected.
Use Core 0.10.0 + SDK 0.8.0 and a compatible host for these extensions, within one Hub and one administrator audit domain. The host owns explicit selection and persistent scope; the standalone MCP server does not gain a multi-system selection UI.
Scenarios, changes and upgrade steps
Conversation archives introduced in 0.4.0
When an Agent Client host enables conversation archiving, a BailingHub administrator can follow the user's request, the assistant's visible replies and the resulting business actions together. For example, one conversation can compare two separately authorized stores while retaining the original execution record for each store. Use BailingHub Core 0.10.0 with a host that captures and synchronizes the conversation. The archive API minimum is Core 0.6.0.
Version 0.4.0 introduced that synchronization API. It does not capture conversations by itself. A native host such as the DSH plugin owns the account selection and conversation interface. The standalone MCP server keeps its existing tool surface.
Who should upgrade, and where to start
Your setup | Next step |
You use an MCP application with a fixed business route | Install this package at |
You use a native Agent Client, such as DSH | Upgrade through that host's matching release and follow its account-selection guide. Installing this MCP command alone does not add a multi-account conversation UI. |
You build an Agent Client host | Install |
You do not need to change business API declarations for this SDK upgrade. Existing read/write, approval and invocation recovery behavior stays in place. Conversation upload retries use the same event IDs and never repeat business actions; only the deployment's authorized administrators can read the combined archive. Hidden reasoning is excluded.
This package is a thin integration adapter. It does not embed BailingHub, grant business permissions, or replace the downstream business system's final authorization. It supports both the existing operator-provisioned Client Token mode and an Agent Session mode in which a human approves one local Agent through the system browser.
What It Exposes
Tool | Purpose |
| Submit untrusted task text to one operator-configured BailingHub route |
| Read the current public state of a credential-owned job |
| Poll one job for at most 60 seconds without resubmitting it |
The Agent Session MCP path starts with seven small meta-tools for turn bootstrap, capability and reference-knowledge search/read, governed invocation/recovery, and visible run completion. BailingHub then returns at most 12 active business tools for the current turn; each replacement removes the previous active set instead of growing the model context indefinitely.
Short tool descriptions can include description_truncated and
usage_guidance_available flags in start/search results. To read only one loaded
tool's bounded guidance, call search_business_capabilities with
{"tool_name":"the_exact_loaded_name","include_usage_guidance":true} after
starting the turn. This is a read-only reference bound to the current run,
authorization and catalog revision; it does not invoke the business tool. Preserve
the returned truncation and size metadata. Older clients without detail support
return a compatibility error; ordinary search remains compatible.
Host implementers should use the host-neutral Agent Client SDK guide.
The route, BailingHub URL, and credential are local process configuration, never model-supplied MCP tool arguments. An SDK host may publish a fixed set of available authorization references for per-call selection within one system; the host resolves each reference to its captured connection and retains control of connection management. See the authorization-reference guidance.
Authentication Modes
Agent Session: run
bailinghub-mcp-server loginonce. The CLI uses a random loopback callback plus PKCE, opens the system browser, and stores the approved session in the platform-specific secure credential store. The MCP tools then use/agent-api/v1/*and refresh rotated tokens locally.Client Token (compatible): when
BAILINGHUB_CLIENT_TOKENis present, the adapter keeps usingPOST /runandGET /jobs/{job_id}exactly as before.
Neither mode lets the model supply a credential, route, acting subject, or approval result. The Agent Session records the identity approved by the Hub/business authorization boundary; the downstream business system still makes the final authorization decision.
The MCP Registry server.json describes only the compatible standalone stdio/Client Token
installation, so that entry still marks BAILINGHUB_CLIENT_TOKEN as required. The native DSH
plugin does not consume that Registry configuration: it imports this package's /sdk subpath as
an ordinary library dependency and establishes an Agent Session through the browser. Do not add a
Client Token field to a DSH plugin based on the Registry form.
Security Model
MCP host / model
|
| request_id + untrusted input
v
BailingHub MCP Server
|
| fixed route + Client Token or approved Agent Session
v
BailingHub
|
| governed dispatch
v
Business system
|
+-- resolves trusted subject and performs final authorizationThe adapter intentionally does not accept:
an acting subject or identity claim;
a Client Token, administrator token, or business-system credential as tool input;
an approval decision or approval evidence;
an executor identity;
arbitrary metadata or callback URLs;
an arbitrary route.
In compatible Client Token mode, use a dedicated token restricted to the one route configured for this server process. Run separate server instances when different MCP clients need different route boundaries.
Install
Prerequisites:
Node.js 20.15 or newer;
a reachable BailingHub deployment;
either one route-scoped BailingHub Client Token or a registered public Agent client that can be approved for the required route.
For the legacy static-job mode, configure an MCP host to spawn:
{
"mcpServers": {
"bailinghub": {
"command": "npx",
"args": ["-y", "bailinghub-mcp-server@0.8.0"],
"env": {
"BAILINGHUB_BASE_URL": "https://hub.example.com",
"BAILINGHUB_CLIENT_TOKEN": "replace-with-a-route-scoped-client-token",
"BAILINGHUB_ROUTE": "order_assistant"
}
}
}
}Agent Session login
Authorize one registered public Agent client and one fixed route before starting the MCP host without a Client Token:
npm install --global bailinghub-mcp-server@0.8.0
bailinghub-mcp-server login \
--base-url https://hub.example.com \
--client-app-id merchant-agent \
--route order-assistant
bailinghub-mcp-server status
bailinghub-mcp-server logoutThe login callback binds only to a random 127.0.0.1 port and uses state plus PKCE S256.
Access and refresh tokens never appear in CLI output. macOS uses Keychain. Linux and other
POSIX platforms require an explicit BAILINGHUB_ALLOW_FILE_CREDENTIAL_STORE=true opt-in;
that fallback rejects files that are not owned by the current user with mode 0600.
Windows uses a CurrentUser DPAPI-protected file under the user's LocalAppData directory. If
Windows PowerShell or DPAPI is unavailable, Agent Session fails closed and never falls back to
plaintext. Compatible Client Token mode remains available on every supported platform.
For a local BailingHub process, loopback HTTP is accepted:
BAILINGHUB_BASE_URL=http://127.0.0.1:3000Non-loopback HTTP is rejected by default. BAILINGHUB_ALLOW_INSECURE_HTTP=true exists only
for an operator-controlled private network where TLS terminates elsewhere. Do not use it
across an untrusted network.
Correct Job Flow
Create a stable
request_idfor one business request.Call
submit_governed_jobwith that ID and the task text.Preserve the returned
job_id.Call
wait_for_governed_jobfor a short bounded wait, or callget_governed_joblater.If submission must be retried, reuse the exact same
request_idand task meaning.
queued, running, and dispatched are non-terminal. done, error, and rejected are
terminal. A wait timeout is not a failed task and must not cause a replacement submission.
First Success and Feedback
Use the MCP integration path as the
canonical start page. The first integration is successful when an MCP host submits through
the operator-fixed route, the same job_id reaches a terminal state, BailingHub retains
its approval and audit state, and the MCP host never receives administrator or
business-system credentials.
Report a PASS, partial result, or failure through the BailingHub independent validation form and select the MCP track. Never include tokens, model keys, personal information, or production business data.
Project Boundaries
The dependency direction is one-way:
bailinghub-mcp-server -> BailingHub public Client API / Agent API
BailingHub may consume ACC declarations
ACC has no dependency on either implementationSee:
Development
npm install
npm run verify
npm pack --dry-runClient Token mode uses the stable bailing.client-api.v1 surface:
POST /runGET /jobs/{job_id}
Agent Session mode uses the additive Agent Auth v1 and Agent API v1 surfaces:
POST /agent-auth/v1/authorizationsPOST /agent-auth/v1/tokenGET /agent-auth/v1/sessionPOST /agent-auth/v1/revokeGET /agent-api/v1/workspacesGET /agent-api/v1/workspaces/{route}/bootstrapPOST /agent-api/v1/workspaces/{route}/turnsPOST /agent-api/v1/workspaces/{route}/capabilities/searchPOST /agent-api/v1/tool-invocationsPOST /agent-api/v1/tool-invocations/{invocation_id}/resumePOST /agent-api/v1/runs/{run_id}/complete
The host SDK additionally uses conversation audit write APIs available from Core 0.6.0. Use Core 0.8.0 for the new cross-system mode, system descriptions and authorization names. These APIs are not exposed as MCP/model tools:
POST /agent-api/v1/conversation-auditsPOST /agent-api/v1/conversation-audits/{conversation_id}/confirmPOST /agent-api/v1/conversation-audits/{conversation_id}/events
The bailinghub-mcp-server/sdk subpath additionally exposes a host-neutral Agent Client factory.
It owns browser login, named local selectors, isolated credentials, token refresh, and Core DTO
mapping. On the same Hub/client/workspace binding it replaces an older local connection only when
Core reports the same trusted on_behalf_of; different business identities remain independently
selectable. Core resolves the business authorization entry, so host adapters such as DSH never ask
for a business URL and do not own credentials or BailingHub HTTP endpoint details.
No administrator, executor, approval-decision, tool-proxy, configuration, or direct business API is called by this adapter.
Available Tools
3 toolsget_governed_jobGet Governed JobARead-onlyIdempotent
Read the current public state and result of a BailingHub job owned by this client.
Inputs: job_id (required).
submit_governed_jobSubmit Governed JobADestructiveIdempotent
Submit a business-system action through an operator-configured BailingHub route. BailingHub applies its configured reach, risk, approval-intent, rate-limit, and audit controls. The downstream business system still performs final authorization.
Inputs: input (required), request_id (required).
wait_for_governed_jobWait for Governed JobARead-onlyIdempotent
Poll one BailingHub job for a bounded period. A timeout returns the latest state and never resubmits the business action.
Inputs: job_id (required), max_wait_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: submitting a job, reading its current state, and polling until completion. Even though get and wait both read state, wait explicitly adds bounded polling behavior, so an agent can easily choose the right one.
All tool names follow a consistent verb_governed_job pattern: submit_, get_, wait_for_. This makes the set predictable and easy to learn.
Three tools is well-scoped for a narrow domain of submitting and monitoring a governed job. There is no bloat or redundancy.
The tool surface covers the full lifecycle for a client: submit the action, retrieve its state, and wait for a result. No obvious operations are missing for the stated purpose.
Maintenance
Related MCP Connectors
Governance runtime for compliance: verified, human-approved writes to a tamper-evident record.
Create, deploy and inspect Eurobase projects and Functions in the European cloud.
Execution control plane for agents: capabilities, durable jobs, budgets, receipts, and BYOK.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables programmatic interaction with Opus workflow automation platform, allowing users to initiate jobs, execute workflows, monitor status, upload files, and retrieve results through the Opus Job Operator API.7MIT
- AlicenseNot gradedqualityBmaintenanceEnables submission, tracking, and retrieval of governed tasks from DeepSeek Harness against BailingHub routes, allowing job management without opening embedded chat interfaces.298 npm2MIT
- -licenseNot gradedqualityNot gradedmaintenanceEnables MCP clients to securely execute bounded coding tasks through registered backends, with idempotent job submission, status polling, and artifact retrieval. It isolates each job in Git worktrees and supports optional branch publishing and pull request creation under strict policy constraints.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients to drive Codex Desktop and codex-app-server as a durable asynchronous worker for long-running tasks, with polling, approvals, Plan Mode workflows, retry safety, diagnostics, and final reporting. It also provides recovery, queueing, and repair tools for reliable local automation.-