Qeasy Cloud
Get Started
Model Context Protocol · Knowledge Retrieval

Qeasy Knowledge MCP Server

An MCP server that gives AI agents expert-level access to Qeasy's continuously synced knowledge across two product lines: e-commerce financial reconciliation (12 knowledge domains, platform topics and customer cases; general methodology and accounting standards are public) and the data integration platform (K1 operations & maintenance, K2 APIs & metadata, K3 design patterns; layered public access). Agents search, inspect and fetch exact evidence with Git-traceable citations — then generate the answer themselves. Standard keys search public knowledge; platform playbooks and customer cases require authorization. One stateless HTTP endpoint: POST /api/mcp.

Live Now: Three Knowledge Tools

The tool surface is discoverable at runtime through MCP `tools/list`. No SDK or generated client is required — any MCP-compatible agent (Claude, Cursor, custom) can connect over plain JSON-RPC.

knowledge_search — find evidence

Hybrid vector + keyword retrieval over the reconciliation knowledge base. Parameters: query (required); product, type filters; limit (1–20, default 8); granularity ('doc' default, or 'atom' for one hit per KA-* knowledge atom); includeMeta (add domain/platform metadata). Returns ranked hits with citation, score and visibility.

knowledge_fetch — open the source

Fetch a full document, or a single knowledge atom, by docId, citation (sourcePath#atomId) or atomId. Optional maxChars caps the response for your token budget. Restricted documents return -32403 unless the key is authorized.

knowledge_domains — route before searching

List the product × type knowledge domains visible to your identity, with document counts. Free of quota — call it first to decide where to search.

Getting Started

The endpoint is stateless: every request carries its own authentication, so it works from serverless agents and multi-instance deployments alike.

Endpoint: POST https://www.qeasy.cloud/api/mcp — JSON-RPC 2.0 over MCP Streamable HTTP (stateless mode). GET/DELETE return 405 and no session is maintained.

Every MCP call requires a key. Agents request /api/v1/agent-registrations/challenge, solve SHA-256 proof-of-work, then register at /api/v1/agent-registrations to receive a Standard key (20 public-knowledge calls/day). No phone, browser session or CRM lead is created. Humans register at /register and also receive a key automatically.

Recommended flow: register agent → initialize → tools/list → knowledge_domains → knowledge_search → knowledge_fetch(citation#atomId).

Claude Desktop / Cursor — mcp.json

{
  "mcpServers": {
    "qeasy-knowledge": {
      "url": "https://www.qeasy.cloud/api/mcp",
      "headers": {
        "Authorization": "Bearer qk_live_YOUR_KEY"
      }
    }
  }
}

Raw JSON-RPC — initialize / tools/list / search / fetch

# 1) request an agent registration challenge
curl -s -X POST https://www.qeasy.cloud/api/v1/agent-registrations/challenge
# => save challengeId and difficulty from data

# 2) solve sha256(challengeId + ':' + nonce) proof-of-work
export CHALLENGE_ID='paste-challenge-id'
export DIFFICULTY='18'
python3 -c 'import hashlib,os
cid=os.environ["CHALLENGE_ID"]; bits=int(os.environ["DIFFICULTY"]); n=0
while True:
 h=hashlib.sha256(f"{cid}:{n}".encode()).digest()
 if int.from_bytes(h[:4],"big") >> (32-bits) == 0: print(n); break
 n+=1'
# => save printed nonce

# 3) register the agent; plaintext key is returned only once
curl -s https://www.qeasy.cloud/api/v1/agent-registrations \
  -H 'content-type: application/json' \
  -d '{"name":"My Agent","framework":"custom","version":"1.0","challengeId":"paste-challenge-id","nonce":"paste-nonce"}'

# 4) call MCP with the Standard key (20 public-knowledge calls/day)
curl -s https://www.qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer qk_live_YOUR_KEY' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

curl -s https://www.qeasy.cloud/api/mcp \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer qk_live_YOUR_KEY' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"knowledge_search","arguments":{"query":"费用按收入占比分摊什么时候合理","granularity":"atom","includeMeta":true}}}'

Response & Citation Contract

Tools return retrieval evidence, never generated prose. The calling agent owns the answer and must cite what it used.

  • Search hits: { docId, title, excerpt (≤500 chars), score, product, type, citation, url, visibility, atomId?, docMeta? } — atomId is present whenever the hit maps to a KA-* knowledge atom, and docMeta only when includeMeta=true.
  • citation format by product domain: reconciliation = `docs/knowledge/<file>.md#KA-...` (Git source path + atom anchor); data-integration = `docs/knowledge/<doc>#section` (or `#chk_...` chunkId) at atom granularity. Always cite this value in the answer; it is stable and auditable.
  • Response shape: content[0].text is a Markdown summary for humans/models; the machine-readable payload is result.structuredContent (hits/page/quota/citation). Do not parse the Markdown for data.
  • granularity="atom" returns one hit per knowledge atom (one chunk for data-integration knowledge) — best for expert rules, thresholds, error codes and edge cases; granularity="doc" folds each document to its best-matching atom.
  • A successful fetch returns the full text (or one atom) plus citation, product/type, visibility and docMeta; maxChars adds truncated:true and originalChars when the response was capped.
  • quota { remaining, resetAt } is included for standard identities; authorized keys omit it. Complete cache HITs consume neither daily quota nor minute allowance; MISS/COALESCED/BYPASS are charged normally.
  • Empty results are not errors: hits:[] plus suggestions. No match usually means the knowledge is restricted (needs an authorized key) or the question is outside the covered knowledge domains.

Access Tiers & Quotas

Two registration paths and two permission tiers. Registration grants Standard only; restricted access still requires Qeasy authorization.

Daily quota resets at 00:00 Asia/Shanghai. The 21st non-cache call returns HTTP 429 + -32029 with errorKind=daily_quota; minute limits use errorKind=minute_rate_limit. initialize/tools/list/knowledge_domains remain free of daily quota.

Standard defaults to 120 requests/minute and authorized to 600. Every call is authenticated, SQL visibility-filtered and audited without plaintext keys or document bodies.

Agent registration — no phone

Open challenge + SHA-256 proof-of-work registration with IP limits, failure audits and database idempotency. No browser session, CRM lead or sales assignment is created.

Standard — issued at registration

Humans and agents automatically receive their first key at registration. Create more at /account (max 5 active keys). Each account includes 20 public-knowledge calls/day, shared by all Standard keys.

Authorized — granted by Qeasy

Unlimited daily calls and the full authorized knowledge base (public + restricted), with configurable product/type scope and expiry. Issued through Qeasy's admin console; contact us to apply.

Two Usage Patterns

One endpoint serves two workflows — pick by task (verified blueprint practice from M24 field testing).

  • Q&A: search for top-k, then fetch one citation#section for the single piece of evidence; excerpts are ≤500 chars, token-friendly.
  • Solution blueprint: narrow first (product + scenario + category + platform; platform accepts path slugs, upstream codes or Chinese vendor names, case-insensitive, e.g. kingdee-cloud, Kingdee.Cloud, 金蝶云星空), then fetch the key sections (field mapping / incrementality / risks) instead of whole documents. Query object/pair-level knowledge with identifiers (interface / object / field names); treat pair documents §7 “no dominant value” marks as the boundary.
  • Honest boundaries: the corpus explicitly marks values it cannot derive (V-class / no-dominant-value); cite the mark instead of fabricating. Restricted cases and solution sets need an authorized key.

Errors & Limits

  • -32001 UNAUTHORIZED — missing, invalid, revoked, expired or disabled-user key (HTTP 401). Follow the human/agent registration hints in the response.
  • -32403 FORBIDDEN — restricted content or a document outside the key scope. data.upgradeHint explains the next step.
  • -32029 RATE_LIMITED — HTTP 429 with errorKind=daily_quota or minute_rate_limit plus Retry-After and RateLimit headers.
  • -32602 INVALID_PARAMS — argument validation failed; message names the offending field (e.g. query empty, limit > 20, bad atomId format).
  • -32601 METHOD_NOT_FOUND — unknown JSON-RPC method; -32600 INVALID_REQUEST — missing method or batch array; -32700 PARSE_ERROR — body is not valid JSON (HTTP 400).
  • -32603 INTERNAL_ERROR — server-side failure; retry with backoff. Request bodies are single JSON objects (batches are rejected).
  • Knowledge scope: the Qeasy reconciliation and data-integration corpora sync continuously; see knowledge_domains for live document/atom counts. Data-integration search supports scenario (S1/S2/S3, default S2) and category (K1/K2/K3) filters. The DataHub platform operations MCP (39 tools) is a separate service — see /skill/datahub. Business write tools are on the roadmap.

Capability Catalog

The official MCP capability catalog (split criterion: whether the Agent task differs, not the product line). Knowledge retrieval shares this endpoint and is split by product domain; per-product operations MCPs are deployed independently and the website only documents them.

Data Integration Knowledge · /mcp/datahub-knowledge

Three categories: K1 platform operations & maintenance, K2 platform APIs & metadata, K3 integration design patterns. Query with product=data-integration plus scenario and category hard filters; citations are sourcePath#section. SOL/CASE/FAIL layers stay restricted.

Reconciliation Knowledge · /mcp/reconciliation-knowledge

12 knowledge domains, platform topics and customer cases (general methodology and tax/accounting standards are public). The reconciliation operations MCP is fully privately deployed; the website currently ships only the knowledge base.

DataHub Platform MCP · /skill/datahub

39 tools (assets / strategies / scripts / audit) with tenant one-click authorization and sh-xxx keys. Public cloud endpoint: pro-service.qliang.cloud/mcp. Private deployments advertise their own endpoints via self-describing keys.

R18 Retrieval & Runtime Hardening

  • Search adds domain/platform filters, stable cursor pagination and minScore. score is normalized 0–1 with vector/keyword/rrf breakdown and matchedOn; off-topic queries return hits:[] instead of unrelated evidence.
  • initialize and tools/list read live identity-visible corpus statistics; knowledge_domains adds stats and domain/platform facets; all three tools declare outputSchema.
  • Query embeddings and retrieval results use TTL caches with same-request coalescing and corpus-revision invalidation. Responses expose X-Qeasy-Cache and Server-Timing.
  • Every response carries X-Request-ID linked to audit logs. CORS/OPTIONS, 401 WWW-Authenticate, a 64 KiB body limit, and standard 120/min + authorized 600/min backpressure are enabled.
  • Health: GET /api/v1/mcp/health performs real PG/Redis/embedding probes. Metrics: GET /api/v1/mcp/metrics requires a separate Bearer token and exposes no PII.

Roadmap

This endpoint is intentional about scope: it is a retrieval server, not a general-purpose business API. The following capability families are planned, not available today — do not build against them yet.

  • connector.invoke / connector.describe — call prebuilt ERP, e-commerce, CRM, WMS and MES connectors with schema-validated parameters.
  • pipeline.run / pipeline.status — trigger and monitor data-integration pipelines.
  • reconciliation.query / reconciliation.explain / reconciliation.draft — query reconciliation results, trace discrepancies and draft vouchers for human confirmation.

Give your agent the reconciliation expert it lacks

Start with a free standard key at /account to explore public knowledge, or apply for an authorized key to unlock the full restricted knowledge base and unlimited calls.

Qeasy Knowledge MCP Server — Reconciliation + Data Integration Knowledge for AI Agents | Qeasy Cloud