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., "@alienprobe-who-mcp look up the legal entity behind apple.com: LEI, jurisdiction, status"
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.
An MCP server that gives any agent one legal-entity fact — LEI, legal name, jurisdiction, entity and registration status — for $0.05 USDC on Base, paid per call over x402. No signup, no API key, no account. The wallet is the account.
Two tools:
Tool | Cost | What it does |
| free | Returns the advertised price, network, payee and coverage. Never pays. Works with no wallet. |
| $0.05, real money | Returns the entity record. Misses and ambiguities cost nothing. |
Three lines. Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):
{ "mcpServers": { "who": { "command": "npx", "args": ["-y", "@alienprobe/who-mcp"],
"env": { "PRIVATE_KEY": "0x...", "MAX_USD_PER_SESSION": "1.00" } } } }Drop the env block entirely and the server still starts — who_terms works, who refuses with wallet_not_configured. That is the safe way to try it.
Related MCP server: gocreative-mcp
Var | Default | Meaning |
| (none) | A throwaway Base-mainnet wallet holding a little USDC. Optional. Never logged, echoed, or returned in a tool result. |
|
| Hard ceiling on one lookup. The lookup is advertised at $0.05. |
|
| Hard ceiling on everything this server process spends before restart. |
See .env.example. Never commit a real key. Fund a wallet that holds nothing else — about $1 of USDC covers 20 lookups. This repo does not tell you how to get USDC onto Base; see https://docs.base.org/base-chain/tools/bridges/.
The server preflights every who call with a plain, unwrapped fetch — no signer exists on that path — reads the advertised price out of the 402, and only then decides. If the price exceeds MAX_USD_PER_CALL, or would push the running total past MAX_USD_PER_SESSION, it refuses with a result the model can read and act on:
{
"error": "spend_cap_exceeded",
"scope": "per_session",
"price_usd": 0.05,
"cap_usd": 1.0,
"spent_usd_this_session": 1.0,
"remaining_usd": 0.0,
"hint": "the session budget is spent; raise MAX_USD_PER_SESSION and restart the MCP server to buy more"
}A session is one server process. Restarting the client resets the counter, so the per-session cap is a brake, not a ledger — the wallet balance is the real ceiling. Keep it small.
A paid hit is the API's body verbatim plus paid_usd:
{
"schema_version": "who-lookup.v1",
"subject": { "type": "who", "value": "apple.com" },
"answer": {
"lei": "HWUPKR0MPOU8FGXBT394",
"legal_name": "Apple Inc.",
"jurisdiction": "US-CA",
"entity_status": "ACTIVE",
"registration_status": "ISSUED",
"match": { "by": "domain", "rule": "domain_exact" },
"official_website": "https://apple.com/"
},
"source": { "name": "...", "vintage": "...", "coverage": "..." },
"paid_usd": 0.05
}q is a company name, a registrable domain, or a 20-character LEI. To disambiguate a name, append a jurisdiction in the same string: "Acme Corp;US-DE".
paid_usd is the authorized price, not the receiptpaid_usd is the amount the server authorized — the price the API advertised in its 402 and that the spend caps were judged against. It is not read back from the chain.
One case where it overstates: a wallet's first successful lookup on this pricing shelf settles at $0 (first-can-free; a property of the service, not of this client). That call still reports "paid_usd": 0.05. Every subsequent call actually moves $0.05.
The server's session counter inherits the same overstatement, which is the safe direction — it stops you early, never late. If you need the truth, the on-chain USDC Transfer from your wallet is the only receipt. Do not use paid_usd for accounting.
These never pay, and they come back as ordinary tool results the model can reason about — not exceptions:
Upstream | Result |
|
|
|
|
|
|
|
|
The API only charges once it can commit to one entity, so an ambiguous re-ask is still free while it stays ambiguous.
No street addresses, no officers or directors, no ownership graph.
No guessing. A miss is a 404, not a best-effort answer.
Legal names that normalize to fewer than 2 Latin alphanumerics (CJK, Cyrillic, Greek, Arabic, Hebrew, Thai) are absent from this data vintage entirely — every door, not just the name door.
Domains match only where the source links an LEI to an official website, on the exact registrable domain. A subdomain misses.
npm install
npm test # 28 contract rows over a mocked fetch: no network, no wallet, no payment
npm run smoke # spawns the server, drives initialize/tools/list/who_terms over real stdionpm run smoke hits the live endpoint to fetch the 402. It runs with PRIVATE_KEY blank and asserts the advertised amount is "50000" ($0.05). It cannot pay.
src/core.mjs holds the transport-free logic and takes an injected fetch, which is why the tests never need a wallet. src/index.mjs is only the MCP wiring; @x402/* and viem are imported lazily, on a call already cleared to pay.
Built on @modelcontextprotocol/sdk 1.30.0. See SPEC.md for the full contract and the distribution plan.
MIT © Brent Bryson. See LICENSE.
SPENDS REAL MONEY: $0.05 USDC on Base mainnet per successful answer, paid from the wallet in the server's PRIVATE_KEY env var. Not a subscription, not credits — an on-chain payment per call. Check who_terms first if the price matters.
Returns exactly one GLEIF Level 1 record: LEI, legal name, jurisdiction, entity status, registration status, last update, how it matched, and (domain queries only) the official website. No addresses, no officers, no ownership graph, no guesses.
FREE refusals — these cost nothing and are returned as ordinary results: invalid_subject (malformed) | not_found (no match) | ambiguous (up to 5 candidates; re-ask with an exact legal_name and a ;jurisdiction suffix) | source_unavailable.
Refuses without paying when the advertised price exceeds MAX_USD_PER_CALL (currently $0.10) or would exceed MAX_USD_PER_SESSION ($1.00). Known gap: legal names that normalize to fewer than 2 Latin alphanumerics (CJK, Cyrillic, Arabic, Hebrew, Thai...) are absent from this data vintage entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Company name, registrable domain (apple.com), or 20-character LEI. Append a jurisdiction to disambiguate a name: "Acme Corp;US-DE". Subdomains do not match. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only read/write safety, but the description discloses the dominant behavioral trait they miss entirely: each call spends $0.05 USDC on-chain from a PRIVATE_KEY wallet, with no subscription/credit model. It also lists the free-refusal outcome codes (invalid_subject, not_found, ambiguous, source_unavailable), the spend caps, and a known data gap for non-Latin scripts — well beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single most decision-critical fact — that this spends real money — is front-loaded in the first sentence, followed by the return contract, then free-refusal cases, caps, and the known gap. Information is chunked and every sentence carries distinct, actionable content with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the exact return fields and all refusal result types. Combined with the cost model, spend caps, and coverage limitation, an agent has everything needed to decide whether to call it and how to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single q parameter is fully documented in the schema, including the ';jurisdiction' suffix and subdomain caveat. The description reinforces the ambiguity/jurisdiction handling but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific action (GLEIF Level 1 legal-entity lookup, exactly one record) and enumerates the returned fields (LEI, legal name, jurisdiction, entity/registration status, match quality, website), plus explicitly delimits scope with 'No addresses, no officers, no ownership graph, no guesses.' It is clearly distinguishable from the sibling who_terms, which is referenced as the pricing lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing ('Check who_terms first if the price matters'), explicit correction guidance for ambiguity ('re-ask with an exact legal_name and a ;jurisdiction suffix'), and states the conditions under which the tool proactively refuses (price exceeds MAX_USD_PER_CALL or MAX_USD_PER_SESSION). This is when-to-use, when-it-won't-work, and alternative-tool guidance all in one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
FREE, read-only. Returns the advertised x402 payment terms for a who lookup — price, asset, network, payee, and the source's coverage statement — without paying anything and without needing a wallet. Use this before who to decide whether the lookup is worth the money (currently $0.05 USDC on Base mainnet). If the subject is malformed, missing or ambiguous, this returns that free refusal instead of terms, which means who would also cost nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Company name, registrable domain (apple.com), or 20-character LEI. Append a jurisdiction to disambiguate a name: "Acme Corp;US-DE". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover only readOnlyHint and openWorldHint; the description adds the material economics the annotation cannot: no payment, no wallet required, the concrete price ($0.05 USDC on Base mainnet), and the free-refusal behavior on bad input. It stops short of describing pagination, caching or rate limits, so a 4 rather than a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the key fact ('FREE, read-only') and then explains purpose, usage, and the edge case in four tight sentences. Slightly dense with parentheticals, but every sentence carries information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description enumerates the returned fields (price, asset, network, payee, coverage statement) and explains the failure response, so the agent knows both the success and failure shapes. Complete for a single-parameter, read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the `q` parameter already documents the accepted forms (name, domain, LEI, jurisdiction suffix). The description references 'the subject' generically but adds no syntax or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Returns the advertised x402 payment terms for a `who` lookup') and enumerates the returned fields — price, asset, network, payee, coverage statement. It is immediately distinguishable from its sibling `who`, which performs the actual paid lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells the agent when to call it: 'Use this before `who` to decide whether the lookup is worth the money.' It also covers the negative case — malformed, missing or ambiguous subjects return a free refusal rather than terms — so the agent knows what a non-term response means.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0whowho_termsScored across 2 tools
The two tools have clearly distinct roles: who_terms is a free, read-only price preview; who is the paid lookup. Descriptions explicitly guide the agent to call who_terms first, and there is no overlap in purpose.
Both tools use lowercase snake_case and share the 'who' stem, but neither follows a standard verb_noun pattern (who is a bare interrogative, who_terms is a noun phrase). Still, the style is consistent and readable.
Two tools are exactly right for a single-purpose lookup service: one free preview and one paid action. No tools are superfluous, and the count avoids bloat for a narrow domain.
The tool set covers the full lifecycle for a paid lookup: check terms, then perform lookup with comprehensive result fields and free refusal handling. The only gap is a data vintage limitation (non-Latin names), which is not a tool surface gap.
China company verification and supplier due diligence data for AI agents via remote MCP and x402 on Base USDC. Basic: 0.032 USDC per call for company registration, operating abnormalities and administrative penalties. Full: 0.093 USDC per call for those 3 modules plus serious violations, enforcement, dishonest judgment debtors, bankruptcy, qualifications and customs (9 modules total, not 9 fields). Structured JSON with per-module availability and limitations. List modules return the first page only, up to 10 records; no automatic pagination or historical expansion. Missing data is not a clean-risk finding. The legacy resolver returns a capability notice only, not a free company lookup. No government procurement coverage. Not a complete due diligence report.
Pay-per-query x402 business intelligence on Base, settled in USDC via the native 402 payment flow.
Market data and web intelligence for AI agents, paid per call in USDC on Base via x402.
Market and on-chain crypto data for AI agents. Pay per call in USDC on Base (x402).
