KHDPConnector
Auth + MCP connector for the Korea Health Data Platform (KHDP), bundled with the SNUH SuperTable SQL client.
khdp is a CLI-first Python package that:
- handles login against the KHDP central auth API,
- ships a Python client (
khdp.supertable.Client) for the SNUH SuperTable SQL gateway over FHIR + OMOP CDM, - exposes both surfaces through a single Model Context Protocol (MCP) server (8 tools — 4 KHDP, 4 SuperTable),
- comes with thin wrappers for Claude Code, OpenAI Codex CLI, and Gemini CLI so the experience is uniform across coding agents.
See supertable/ at the repo root for SuperTable
quickstart, full usage notes, runnable examples, and the Claude Code
skill file. The Python module is at src/khdp/supertable/.
Status: alpha. APIs and tool names may move during Phase 0–1 of the PLAN.md roadmap.
How it talks to KHDP
The connector uses KHDP's password-based auth API. It implements two endpoints that are safe for headless / CLI use:
POST /_api/oauth/login {appId, redirectUrl, mail, password}→{accessToken, refreshToken, expireTime}POST /_api/member/refresh-token {refreshToken}→ same shape, rotated.
All subsequent KHDP API calls go out with Authorization: Bearer <accessToken>.
┌────────────────────────────────────────────────────────────┐
│ Claude Code · Codex CLI · Gemini CLI · … │
│ │ │ │ │
│ └──────── MCP (stdio JSON-RPC) ───────┐ │
│ ▼ │
│ khdp-connector (this) │
│ │ │
│ ▼ │
│ POST /_api/oauth/login POST /_api/member/... │
│ (login + refresh) (any KHDP endpoint) │
│ khdp.net │
└────────────────────────────────────────────────────────────┘
Install
pipx install khdp-connector # recommended; isolates from system Python
# or
pip install khdp-connector
# or with OS-keychain support:
pipx install 'khdp-connector[keyring]'
One-time configuration
You need a KHDP-registered app_id (UUID) and a registered
redirect_url. Drop them into a config file or env vars:
# ./khdp.local.toml
app_id = "00000000-0000-0000-0000-000000000000"
redirect_url = "https://example.org/khdp-cli"
api_base = "https://khdp.net/_api" # default; override for staging
…or:
export KHDP_APP_ID=00000000-0000-0000-0000-000000000000
export KHDP_REDIRECT_URL=https://example.org/khdp-cli
Don't have an
app_idyet? Coordinate with the KHDP team to register a CLI-class app. snuh.ai's publicapp_idwon't work for the CLI — itsredirect_urlallowlist excludes anything outsidesnuh.ai.
CLI usage
khdp login # prompts for email + password (or use --email / --password-stdin)
khdp status # is a token cached? when does it expire?
khdp refresh # force a refresh-token rotation
khdp api GET /member/me # authenticated KHDP API call
khdp logout # delete cached tokens
khdp config # print resolved configuration
khdp mcp # run the MCP server on stdio (for agents)
Configuration resolution order (highest first):
KHDP_*environment variableskhdp.local.tomlin the current working directory~/.config/khdp/config.toml(or platform equivalent)- Built-in defaults
For non-interactive use:
KHDP_EMAIL=me@example.com khdp login --password-stdin <<< "$KHDP_PASSWORD"
MCP server
khdp mcp
# or
khdp-mcp
Tools exposed on stdio:
| Tool | Purpose |
|---|---|
khdp_auth_status |
Is the user logged in? When does the token expire? |
khdp_auth_refresh |
Rotate the refresh token to extend the session. |
khdp_auth_logout |
Delete locally cached tokens. |
khdp_api_request |
Authenticated HTTP passthrough to the KHDP API. |
The MCP server never accepts a password through tool arguments —
passwords would otherwise flow through the LLM context window. Login
is initiated out-of-band via khdp login in the user's terminal; the
MCP server just reads the resulting token cache.
Future tools (per PLAN.md) will add dataset I/O, OMOP queries, audit log retrieval, and IRB result-pinning.
Wrappers
The same MCP server backs a thin wrapper per agent platform.
Claude Code
claude mcp add khdp -- khdp mcp
cp -r wrappers/claude-code/skills/khdp-auth ~/.claude/skills/
OpenAI Codex CLI
Append wrappers/codex/config.example.toml to ~/.codex/config.toml,
copy wrappers/codex/AGENTS.md to your project root.
Gemini CLI
Merge wrappers/gemini/settings.example.json into
~/.gemini/settings.json, or install as a Gemini Extension under
.gemini/extensions/khdp/.
Development
git clone https://github.com/KoreaHealthDataPlatform/KHDPConnector.git
cd KHDPConnector
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e '.[dev,keyring]'
pytest
Security model
- No secret in the binary. The CLI ships only the user-provided
app_id. There is no embedded client secret. - Password never leaves the local machine unencrypted; it goes only to KHDP's TLS endpoint, never to the LLM, never to the MCP context. The MCP tool surface deliberately omits a password argument.
- Per-app token isolation. Multiple KHDP apps on one machine are
kept separate by
app_id. - Token storage. OS keychain (Keychain / Credential Manager /
Secret Service) when the
keyringextra is installed; otherwise a JSON file with0600permissions in the platform user-config dir. - No revocation endpoint exposed by KHDP today.
khdp logoutonly clears local state. Access tokens expire naturally; refresh tokens go invalid the next time the access token is rotated.
Roadmap
See PLAN.md for the full roadmap. The current implementation covers Phase 1 (auth) and a generic API passthrough. Dataset I/O, OMOP analysis, and IRB-grade result pinning land in later phases.
License
Apache 2.0. See LICENSE.
Metadata
Release files for khdp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| khdp-0.2.0.tar.gz | 49.8 kB | Without provenance | Details for khdp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| khdp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for khdp-0.2.0-py3-none-any.whl |
Total release size: 80.0 kB
Release files / khdp-0.2.0.tar.gz
| Download URL | khdp-0.2.0.tar.gz |
|---|---|
| Size | 49.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fb007de1ad36d7633153f4ea8a368c5e16e566507edfbdb34cd18813a505bd93
|
|
BLAKE2b-256 checksum How to use checksums |
00e7d4369ecf3bbd2e0483c09fc6d6bee388ef62c5efb4924c81aa32bc703b39
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Release files / khdp-0.2.0-py3-none-any.whl
| Download URL | khdp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 30.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a4ecc6c887277d853e4752406e6c279bb1c218d1468141af572d8c1968b34cb
|
|
BLAKE2b-256 checksum How to use checksums |
b1ecc01c8824b98cd257b57257b82a541a850a7ca2791aafad3922a9cd3a6288
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.9
|
Security for khdp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.