DataCore A2A

DataCore A2A — MCP server

English · Tiếng Việt

Lets an MCP client (Claude Code, Claude Desktop, VS Code, Cursor…) use DataCore's data skills as native tools: normalise Vietnamese addresses, validate an address, look up a company, generate embeddings.

MCP client (stdio) ──► datacore-mcp ──HTTPS──► DataCore gateway

Zero dependencies, Python 3.9+.

Quick start

This server is a client, not a service. It needs a DataCore endpoint and a credential to call it with. Missing either one, it starts, says which variable is absent, and exits.

You need an account on datacore.vn first.

1. Install

pip install datacore-a2a-mcp

If you installed from GitHub while this was unreleased, --upgrade will not move you to the PyPI build — uninstall first, then install again.

2. Get a session token

Sign in at datacore.vn, then copy the token request header from any call to gateway.datacore.vn (DevTools → Network). 64 hex chars.

No curl equivalent: POST /auth/login RSA-decrypts the password and no endpoint publishes the public key, so only the web app can complete a login. A credential page will remove this step.

Ignore the jwt from the same login — the gateway rejects client-supplied Authorization with 409; token is the header it accepts.

3. Create a credential

curl -s -X POST https://gateway.datacore.vn/mcp/credentials \
  -H "token: <64-character token>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"claude-code"}' | jq .

201 with the credential, including api_key, key_prefix, allowed_skills, spend_cap_vnd and quota_period.

Copy api_key straight away — it is returned once. Only a hash is stored, so there is no way to read it back. Lose it and you create a new one.

A 409 here means you are already holding the maximum of 3 active credentials. Revoke one first (see Quotas and limits).

4. Declare it in your client

See Configuration below.

There is no web UI for steps 2–3 yet; curl is the way. When a management page exists, these commands keep working.

Quotas and limits

Free tier	500,000 VND of spend per credential per month
Price per call	500 VND by default, so roughly 1,000 calls
Reset	1st of the month, Asia/Ho_Chi_Minh
Credentials	at most 3 active per account
Credential lifetime	90 days
Mandate issuance	at most 10 exchanges per minute per credential

The cap is counted per credential, not per account — three credentials give an account three separate caps. The service meters in VND rather than in calls so that per-skill prices can be introduced later without rewriting stored caps.

A credential is not bound to a machine or an IP, so the same key works from another computer — on one shared quota, and one revocation kills both.

Check what a credential has spent, and revoke it:

curl -s https://gateway.datacore.vn/mcp/credentials/<id>/usage -H "token: <token>" | jq .
curl -s https://gateway.datacore.vn/mcp/credentials -H "token: <token>" | jq .
curl -X DELETE https://gateway.datacore.vn/mcp/credentials/<id> -H "token: <token>"

/usage reports spent_vnd, spend_cap_vnd, quota_period and resets_at. Revocation returns 204, and 404 if the id is not yours — the two cases are deliberately indistinguishable.

Configuration

Variable	Required	Meaning
DATACORE_A2A_URL	yes	Base URL of the DataCore gateway — https://gateway.datacore.vn, unless you were given your own endpoint
DATACORE_API_KEY	yes¹	Long-lived credential, shaped dck_<prefix>_<secret>. The server exchanges it for short-lived mandates and refreshes them itself
DATACORE_MANDATE	yes¹	A hand-issued AP2 mandate. Only for callers set up the old way — see below
DATACORE_SKILLS	no	Comma-separated skill ids to narrow the tool list, or * for everything the endpoint returns. Empty uses the default four
DATACORE_TIMEOUT	no	Per-request timeout in seconds, default 30

¹ One of the two is required. If both are set, DATACORE_MANDATE wins.

Use the URL DataCore gave you. A different endpoint will not recognise your credential and answers 401.

Why DATACORE_API_KEY is the one to use

A mandate lives 15 minutes. With DATACORE_API_KEY, the server requests a fresh one a minute before the current one expires, so you never edit a config file because a token ran out. The mandate stays in process memory and is never written anywhere. If a call still comes back 401, the server forces one refresh and retries exactly once before reporting the failure.

DATACORE_MANDATE still works and is never refreshed — it is there for anyone configured before credentials existed. When it expires you replace it by hand and restart the MCP server.

Claude Code

claude mcp add datacore-a2a -s user \
  -e DATACORE_A2A_URL=https://gateway.datacore.vn \
  -e DATACORE_API_KEY=<YOUR_API_KEY> \
  -- datacore-mcp

Replace <YOUR_API_KEY> with the api_key from step 3 — it looks like dck_<8 hex chars>_<secret>.

-s user registers it for every project. Prefer this over a project-scope .mcp.json: that file tends to get committed, and the key is a 90-day bearer credential.

Claude Desktop

Merge the block below into the config — do not replace the file, it holds your app preferences.

OS	Config path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "datacore-a2a": {
      "command": "<PATH_TO_DATACORE_MCP>",
      "env": {
        "DATACORE_A2A_URL": "https://gateway.datacore.vn",
        "DATACORE_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Both <...> values are yours to fill in — JSON has no comments, so nothing in the file will remind you:

Placeholder	Where it comes from
<PATH_TO_DATACORE_MCP>	which datacore-mcp (macOS/Linux) or where datacore-mcp (Windows). Something like /home/you/.local/bin/datacore-mcp or C:\Users\you\AppData\Roaming\Python\Scripts\datacore-mcp.exe
<YOUR_API_KEY>	the api_key from step 3, shaped dck_<8 hex chars>_<secret>

It has to be an absolute path: the desktop app does not inherit your shell PATH, so a bare command name usually fails to start. python -m datacore_mcp.server works too. Then quit the app completely — closing the window is not enough.

Logs go to stderr, which the app keeps in the logs/ directory beside that config file.

Tools

The tool list is generated from the endpoint, not hardcoded here — so when DataCore adds a skill, restarting the server is enough to see a new tool.

Five skills are exposed by default, the ones wired to a real backend:

Tool	Skill id	What it does
address_normalize	address.normalize	Normalises a Vietnamese address into province / district / ward
address_validate	address.validate	Checks an address against administrative data
company_search	company.search	Looks a company up by name or tax code
company_graph	company.graph	Returns the company's relationships — representative, province, industry, and anything else the graph holds
company_embeddings	company.embeddings	Generates an embedding vector for a piece of text

Every tool takes one required argument, text, a free-text string; no other properties are accepted. Every tool is read-only (readOnlyHint: true): nothing is written, deleted or created, and the same input gives the same result.

DataCore's two other skills (company.financial-sankey, company.news) are deliberately not exposed: they currently return mock/deterministic data. Setting DATACORE_SKILLS="*" lists them as tools, but a free-tier credential cannot call them — its allowlist holds only the five skills above, so every call returns 403. Asking for extra skills when creating a credential is not an error either; the request is silently narrowed to the five.

company.graph used to be on that list. It now reads real relationships, so a credential created before this release does not include it — the allowed skills are written into each credential when it is issued. Create a new one to pick it up.

Examples

Three prompts that go through three different tools:

1. Normalise an address — "Normalise this address into province/district/ward: So 1 Ly Thai To, Hoan Kiem, Ha Noi"
2. Company lookup — "Find the company with tax code 0100109106 and tell me whether it is still operating"
3. Embedding — "Generate an embedding for this line of business and tell me how many dimensions the vector has: wholesale of electronic equipment"

Security model

This server carries the mandate verbatim in the X-AP2-Mandate header for DataCore to verify, and declares no authorization header of its own. A client has no business authorizing itself — it forwards what it was given, and every allow or deny decision stays on the DataCore side.

The API key travels in X-Datacore-Credential when exchanged for a mandate, not in Authorization. DataCore's gateway keeps Authorization for itself — it signs and injects that header after authenticating the caller — so any request that arrives carrying one is rejected with 409 and an empty body. If you call /mandate/issue by hand and get a 409 with no message, that is why.

The API key is a bearer credential: whoever holds it can exchange it for a mandate and call the skills it allows until the cap runs out. Treat it like a password — do not commit a filled-in .mcp.json, and if your client supports it, read the key from a secret manager instead of inlining it. If it leaks, revoke it immediately with DELETE /mcp/credentials/<id> (see Quotas and limits); mandates already issued from it keep working for the rest of their 15 minutes — there is no instant revocation list.

The mandate is the opposite: 15 minutes of life, process memory only. It is not written to disk, never logged, and you should never need to look at it.

Issuance is rate-limited to 10 exchanges per minute per credential, so the endpoint cannot be used to walk the key space. Every rejection — unknown key, revoked key, expired key, wrong secret — returns the same 401 message for the same reason.

This package never logs a token, not even partially, and never logs the text you send. That is a promise about the process running on your machine — the service side is a separate matter, and PRIVACY.md says plainly what it stores.

Troubleshooting

Logs go to stderr, prefixed [datacore-mcp]. stdout is the JSON-RPC channel.

Symptom	Usual cause
Exits at once, MISSING required environment variable	DATACORE_A2A_URL is not set
Exits at once, MISSING authentication	Neither DATACORE_API_KEY nor DATACORE_MANDATE is set
DATACORE_API_KEY appears to be ignored	You are on 0.1.0, which predates credentials and reads only DATACORE_MANDATE. Upgrade: pip install -U datacore-a2a-mcp
401 on everything	The credential was revoked, or is past 90 days, or DATACORE_A2A_URL is not the endpoint that issued it. On DATACORE_MANDATE: the mandate expired and is not refreshed. One message covers all of them on purpose, so the endpoint cannot be used to probe for valid keys. To tell them apart, call GET /mcp/credentials and see whether yours is still ACTIVE
409 calling /mandate/issue by hand	You put the key in Authorization. It belongs in X-Datacore-Credential. The package gets this right; you only hit it calling by hand
409 creating a credential	You already hold 3 active ones. Revoke one first
429	More than 10 mandate exchanges in a minute for one credential. The package refreshes about four times an hour, so this means something is looping
402	This month's cap for that credential is spent. It resets on the 1st
403	The skill is outside the credential's allowlist — the free tier covers only the four skills above, and that set cannot be widened
400	Malformed request, or the skill id is not registered at the endpoint
404	No such route — check DATACORE_A2A_URL
502 / 503	The backend behind that skill is not answering
No tools at all	DATACORE_SKILLS filtered everything out, or the endpoint has no skills registered

Reporting a security issue

[email protected]. Please do not open a public issue for a security bug.

If you think your credential has leaked, report it now — do not wait for it to expire. We need to know so we can act on the service side.

Privacy

See PRIVACY.md. In short: this package runs on your machine, stores nothing, sends nothing anywhere except the DataCore endpoint you configured, and never writes a mandate token to a log.

License

MIT — see LICENSE.