zvex-trade Connector Manual

1. What this is

zvex-trade is an MCP data connector: real trade data (company records, customs leads, company profiles) queried in a controlled way from your AI client. The connector answers "can it be found"; your AI answers "how to use it".

Data honesty is the core design: every query carries a coverage-gap statement (meta.coverage_gaps) telling you where the data is thin and how much to discount conclusions. We do not hide weaknesses.

2. What it can query

Capability	Description	Status
search_company	Filter candidate companies by country/industry/product/name (paged + signed cursors)	✓
profile_company	Research card per company: facts, matching evidence, counter-evidence, verification questions	✓
describe_coverage	One-sentence boundary report per market (free)	✓
account_status	Current tier, today's usage and remaining quota	✓
research tasks	Read / cancel research tasks	✓
hs_filter / time_filter / trade_amount_trend / trade_history / verified_contact	HS filtering, time-window filtering, amount trends, trade history, verified contacts — data does not support these; honestly disabled	✗ (declared)

Scale and blind spots come from describe_coverage's live response — never assume from memory.

3. Connect

WorkBuddy (recommended)

WorkBuddy → Connector market → search "声桥" / "zvex-trade" → install.
After authorization, ask your AI: "What can you find for the Brazil market?" — a boundary response with gap statements means you're connected.

Claude Code / Cursor (manual)

{ "mcpServers": { "zvex-trade": {
  "url": "https://zvex.cn/trade/mcp",
  "headers": { "Authorization": "Bearer <YOUR_API_KEY>" }
} } }

Custom agents

Connect directly to POST https://zvex.cn/trade/mcp (Streamable HTTP: initialize → mcp-session-id → notifications/initialized → tools/call). The server sends usage discipline (instructions) on initialize — custom agents must put it into the system prompt; HTTP timeout ≥60s recommended; API keys live only on your own server, never shipped to clients or frontends.

4. Authorization & accounts

Two forms: account login (WorkBuddy OAuth) or API key (Bearer). Never configure both — two connections on one endpoint means auth eventually goes stale; symptom: "works sometimes".
Keys live in your own server / client configuration; never commit them or share them.
New accounts include a free trial (10 queries/day); upgrade to Personal to restore quota after it ends.

5. Self-check & troubleshooting

The installer ships a self-check script (trade_check.sh) — probe only, no changes:

bash trade_check.sh                  # no key: verifies endpoint online + auth on
ZVEX_TRADE_KEY=sk-xxx bash trade_check.sh   # with key: verifies key + tools

Six outcomes: ✓ N tools available (ready) / ✗ invalid key (401) (re-issue in console) / ✗ cannot connect (network/DNS) / ✗ unexpected status, please report / ✓ account form: no key on this machine — normal / key stored encrypted and unreadable — rerun with --key.

What you should see after install: "声桥 connector · connected" in your connection list; asking "what can you find for the US market" returns a data boundary with gap statements.

6. Tools missing? Suspect the client first

Client truncates the capability list — some clients show only the first N tools or filter by name;
The AI invents tool names — the model hallucinates tools/parameters and the query degrades into a no-op;
Misconfigured endpoint / mixed auth forms — see chapter 4.

Hard criterion: ask the AI to list the parameter names it intends to call, and check them against the chapter-2 table. If it can't, or they don't match — client truncation / model hallucination, not a connector problem.

Feedback needs four things: which client / which capability / the AI's reported parameter names / a screenshot of the conversation. contact@zvex.cn

7. How to ask (12 real examples)

Responses below are captured from production (2026-11-05).

Ex 1 · Scout before you query free

Ask: "What can you find for Brazil?" → describe_coverage("Brazil")
You get: {"has_records": true, "volume_bucket": "medium", "coverage_gaps": [hs_code_missing, …]} — records exist, medium volume, gap statements and bilingual name hints.

Cost: 0 (describe_coverage is free)

Ex 2 · Candidates by country 1 query

Ask: "Textile candidates in Brazil?" → search_company({"country":"Brazil"}, limit=3)
You get: candidates array (display_name / company_handle / country / supplier / source_segment…) + next_cursor + meta.coverage_gaps.

Cost: 1 (only when results exist)

Ex 3 · Company research card not counted

Ask: "Detailed profile of the first one" → profile_company(company_handle)
You get: research card (facts / matching_evidence / counterevidence / verification_questions) + dual-name check (customs registered name vs profile name; mismatch prompts "verify first"). No contact details.

Cost: 0 (profile is not counted)

Ex 4 · Cold market (honest three-state) not counted

Ask for a market not in the database → result_state: "not_collected", warnings[0] = "Not collected: no records for this market — not a risk signal, just coverage (no charge)".

Cost: 0

Ex 5 · Remaining quota not counted

Ask: "How much quota is left?" → account_status
You get: {"tier": "personal", "daily_used": 3, "daily_limit": 500, "balance_remaining": 497}.

Cost: 0

Ex 6 · Idempotent replay replay free

Retries/double-clicks replaying the same X-Idempotency-Key within 24h: returns the first cached result + warning "幂等键命中，本次未重复扣费 (idempotent hit, not charged again)" + meta.idempotent_replay = true.

Cost: 0 for replays

Ex 7 · Bilingual country names free

Country names exist in both scripts (e.g. 「印度」/India, tens of thousands each): describe_coverage and query warnings both suggest "try both spellings".

Cost: 0

Ex 8 · Gap self-check with every query

meta.coverage_gaps carries five codes (see chapter 9 table), each with a plain-language discount note. Your AI is obliged to tell you — if it doesn't, show it this chapter.

—

Ex 9 · Time semantics with every query

Without time parameters, reasoning.default_window echoes: "observation-period coverage (no usable trade-date field, no time filtering… do not draw recency/trend conclusions)".

—

Ex 10 · Paging each page counts

When results exceed one page, next_cursor is returned: pass it as the cursor parameter for the next page. Signed cursors are bound to your org/conditions/snapshot — tampering is rejected.

1 per page (when results exist)

Ex 11 · Same-name companies with every query

Multiple hits on one name trigger a note: "same-name ambiguity: not merged, disambiguate by country and source record" — same name ≠ same company.

—

Ex 12 · Self-check three states free

"The connector won't connect" → run the chapter-5 check: anonymous returns "no key on this machine — normal"; wrong key returns "✗ invalid key (401)"; correct key returns "✓ 8 tools available".

Cost: 0

8. Billing

What counts: a search_company call with results = 1; each page of paging counts separately.
What doesn't: zero results / not collected / faults / idempotent replays / describe_coverage / profile / account_status — never counted.
Each response's billing key carries whether it counted and today's remaining; quota numbers and details live in the console.

9. Message meanings

Code/message	Meaning	How it discounts conclusions
hs_code_missing	No HS-code field	Category matching relies on text; misclassification possible
amount_missing	No amount field	"Big buyer" conclusions cannot be verified
date_sparse	No usable trade-date field	No time-window / frequency / trend judgments
country_partial	~40% of customs records lack country	Country filters miss these; "no such product in country X" is unreliable
data_lag	Timestamps are import times, not trade times	Recency conclusions unreliable; use meta.data_as_of
zero_result	True absence: market has records, no filter match	Retry with industry/product keywords
not_collected	Not collected: market not covered by the source	Not a risk signal; don't read as "market is clean"
dual-name mismatch	Customs registered name ≠ profile name	Treat as a signal, verify first — the system doesn't hide it

10. FAQ & version

Empty results — bad data?Check warnings[0] first: "true absence" vs "not collected"; confirm with describe_coverage.
The AI answered with no data, all made up?Chapter-6 hard criterion: make it report parameter names against the capability table.
Export?Per-query page limits are in account_status; larger batches are enterprise — contact contact@zvex.cn.
How fresh is the data?See meta.data_as_of (active snapshot time).

Version: this manual matches connector v0.5.0 (check serverInfo.version on initialize).

zvex-trade Trade Data Connector · Manual

1. What this is

2. What it can query

3. Connect

WorkBuddy (recommended)

Claude Code / Cursor (manual)

Custom agents

4. Authorization & accounts

5. Self-check & troubleshooting

6. Tools missing? Suspect the client first

7. How to ask (12 real examples)

8. Billing

9. Message meanings

10. FAQ & version