Skip to main content
Glama
bailinghub-mcp-server

bailinghub-mcp-server

Official
by bailinghub

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.

Changes · Upgrade

简体中文 | 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 0.8.0 using the MCP setup below. Your existing Client Token and Agent Session flows remain compatible.

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 bailinghub-mcp-server@0.8.0, use Core 0.10.0 for the complete feature set, and follow the SDK guide.

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_governed_job

Submit untrusted task text to one operator-configured BailingHub route

get_governed_job

Read the current public state of a credential-owned job

wait_for_governed_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 login once. 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_TOKEN is present, the adapter keeps using POST /run and GET /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 authorization

The 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 logout

The 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:3000

Non-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

  1. Create a stable request_id for one business request.

  2. Call submit_governed_job with that ID and the task text.

  3. Preserve the returned job_id.

  4. Call wait_for_governed_job for a short bounded wait, or call get_governed_job later.

  5. If submission must be retried, reuse the exact same request_id and 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 implementation

See:

Development

npm install
npm run verify
npm pack --dry-run

Client Token mode uses the stable bailing.client-api.v1 surface:

  • POST /run

  • GET /jobs/{job_id}

Agent Session mode uses the additive Agent Auth v1 and Agent API v1 surfaces:

  • POST /agent-auth/v1/authorizations

  • POST /agent-auth/v1/token

  • GET /agent-auth/v1/session

  • POST /agent-auth/v1/revoke

  • GET /agent-api/v1/workspaces

  • GET /agent-api/v1/workspaces/{route}/bootstrap

  • POST /agent-api/v1/workspaces/{route}/turns

  • POST /agent-api/v1/workspaces/{route}/capabilities/search

  • POST /agent-api/v1/tool-invocations

  • POST /agent-api/v1/tool-invocations/{invocation_id}/resume

  • POST /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-audits

  • POST /agent-api/v1/conversation-audits/{conversation_id}/confirm

  • POST /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 tools
get_governed_jobGet Governed JobA
Read-onlyIdempotent

Read the current public state and result of a BailingHub job owned by this client.

Inputs: job_id (required).

submit_governed_jobSubmit Governed JobA
DestructiveIdempotent

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 JobA
Read-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

    A4.4/5.0

    Scored across 3 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All tool names follow a consistent verb_governed_job pattern: submit_, get_, wait_for_. This makes the set predictable and easy to learn.

    Tool Count5/5

    Three tools is well-scoped for a narrow domain of submitting and monitoring a governed job. There is no bloat or redundancy.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      7
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -