vn.datacore/datacore-a2a
OfficialREADME.md
# DataCore A2A — MCP server
<!-- mcp-name: vn.datacore/datacore-a2a -->
<!-- Fallback marker: the registry looks for a substring, so both lines can
coexist. Keeps a way back if domain verification does not land, without
publishing a new version just to fix a comment line.
mcp-name: io.github.nambn3tit/datacore-a2a-mcp -->
<!-- Links in this file are absolute on purpose. This file is the long
description on PyPI, and PyPI rewrites heading ids to `user-content-*`
without rewriting the links that point at them — so a relative link or a
bare `#anchor` renders as a dead link there. README.vi.md is only ever read
on GitHub, so it keeps the short forms. -->
**English** · [Tiếng Việt](https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/README.vi.md)
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](https://datacore.vn) first.
### 1. Install
```bash
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](https://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
```bash
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](https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/README.md#quotas-and-limits)).
### 4. Declare it in your client
See
[Configuration](https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/README.md#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
| | |
|---|---|
| Requests | 1,000 per account in a sliding 30-day window |
| What counts | every call that reached a skill and got an answer |
| Credentials | at most 3 active per account |
| Credential lifetime | 90 days |
| Mandate issuance | at most 10 exchanges per minute per credential |
The quota belongs to the **account**, not to a credential: every key you hold
and Claude Connect draw from the same 1,000. Revoking a key or creating a new one
does not reset it. The window slides, so there is no reset date — a request comes
back 30 days after it was made.
A call that finds nothing (no matching company, say) still counts: the work was
done. A call that fails because DataCore could not reach the backend does not,
and neither does a call refused before it ran (skill not allowed, bad mandate,
quota already used).
Past the quota, calls get `429` with
`QUOTA_EXCEEDED: Used 1000 of 1000 requests in the last 30 days; next slot at <time>`
and a `Retry-After` header in seconds.
A credential is not bound to a machine or an IP, so the same key works from
another computer — and one revocation kills both.
Check usage, list your keys, and revoke one:
```bash
curl -s https://gateway.datacore.vn/mcp/credentials/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>"
```
`/mcp/credentials/usage` reports `used`, `limit`, `remaining`, `window_days`,
`oldest_counted_at` and `next_slot_at` — when the next request comes back. The
list shows `requests_30d` for each key. 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 lists every skill your credential is allowed to call |
| `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
```bash
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` |
```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.
The table is not the whole list. The server lists **every skill your
credential is allowed to call** — the `allowed_skills` in the mandate it holds —
so when DataCore enables a skill for your tier (for example `dataset.list`,
`dataset.query`, `company.financial-sankey`), it shows up after you restart the
server, with nothing to change on your side. Skills the endpoint knows but your
credential cannot call are left out, because every call to them would return
`403`; `DATACORE_SKILLS="*"` lists them anyway.
The allowed skills are read when each mandate is issued, not when the credential
is created, so an existing credential picks up a newly enabled skill within one
mandate lifetime (15 minutes at most).
## 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](https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/README.md#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](https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/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` (getting a mandate) | 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 |
| `429` `QUOTA_EXCEEDED` | The account's 1,000 requests in the last 30 days are used — across every key and Claude Connect. The error says when the next one comes back; `Retry-After` gives it in seconds |
| `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
`mcp-security@datacore.vn`. 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](https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/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](https://github.com/DataCore-VietNam/datacore-a2a-mcp/blob/master/LICENSE).