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

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: " | jq . curl -X DELETE https://gateway.datacore.vn/mcp/credentials/ -H "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

¹ 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= \ -- datacore-mcp

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

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

{

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

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

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:

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/ (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.

| S