und-mcp
A small, local Model Context Protocol (MCP) wrapper that exposes the und public API as tools you can call from Claude Desktop or Claude Code.
It runs on your machine over stdio. It holds your API key, makes
read-only GET calls to the und public API, and returns the results to
Claude. It contains no business logic beyond mapping each named tool to a single
API request.
What it does
The wrapper exposes one tool in v1:
| Tool | What it returns |
|---|---|
run_test(limit, offset) |
Your key's identity plus a project-scoped sample of und_master_summary rows (filtered to your key's project). Use it to confirm your key works and to see exactly what your key's project can read. |
run_test maps to GET {UND_API_URL}/api/v1/test. The /test endpoint
returns a project-scoped sample of und_master_summary — specifically,
und_master_summary rows filtered by your key's project name (its vendor
field). Keys are project-scoped, including rep projects: a rep key does
not automatically reach the vendors it is associated with, so it may return
no rows. The limit argument is capped at 200 server-side; offset paginates
the sample.
More data tools will be added in a later release as the API grows.
API documentation (for clients and AI tools)
The API publishes an auto-generated OpenAPI spec at
{UND_API_URL}/api/v1/docs/openapi.json (public, no key required; Swagger UI
at /api/v1/docs/ui, ReDoc at /api/v1/docs/redoc). The spec is generated
from the server code, so it is the single source of truth for the
endpoints, their query parameters (including the limit/offset pagination
contract), and the request/response schemas. Clients and AI tools should
consume that document to learn the API's shapes instead of guessing or
relying on prose documentation: fetch it at {UND_API_URL}/api/v1/docs/openapi.json,
and treat the error envelope there ({"error", "status"} with fixed
server-defined messages) as the complete set of error responses.
Prerequisites
- Python 3.11+
- An und API key (
und_...) scoped to your project — vendor orrep. Ask the und team to issue one for you. Keys are project-scoped: the API only ever returns data your key's project is authorized to read. - The confirmed und API host (the base URL, e.g. an
https://...host). Ask the und team for the confirmed HTTPS host and set it viaUND_API_URLorconfig.tomlbefore using a real key — the wrapper has no default host and will not start on a key alone.
Quickstart (no Python experience needed)
This path is for non-technical clients — it needs no Python knowledge
and no pre-existing Python setup. The uv tool installs and runs the wrapper
for you, so you can skip straight to configuring Claude.
1. Install uv with the official one-liner for your platform:
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2. Configure Claude Desktop. Edit
claude_desktop_config.json (on macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"und": {
"command": "uvx",
"args": ["und-mcp"],
"env": {
"UND_API_URL": "https://api.example.com",
"UND_API_KEY": "und_..."
}
}
}
}
Both values are required — a key without UND_API_URL will not start the
server. The UND_API_URL value above is an obvious placeholder
(api.example.com is a reserved domain, not a live host) — obtain the
confirmed und API host from the und team and replace the placeholder before
using a real key.
3. Restart Claude Desktop. You'll see the und server and its
run_test tool available.
You never install und-mcp yourself in this path: when Claude Desktop starts
the server, uvx automatically downloads und-mcp from PyPI into an
isolated, cached environment and runs it. The first start is slower and
needs internet; later starts reuse the local cache.
If the und server does not appear after restart, Claude Desktop may not find
the uvx command — GUI apps do not inherit your shell PATH. Run
which uvx in a terminal and use the printed absolute path as the
"command" value in the config above.
Installation
Two supported paths install the und-mcp command (both pin mcp==2.3.0 +
httpx==0.28.1):
Recommended — install with pipx:
pipx install und-mcp
(pipx needs a Python 3.11+ interpreter available to it — see
Prerequisites.)
Zero-install — run with uvx:
uvx und-mcp
To run a newly published version, use uvx und-mcp@latest — plain uvx und-mcp reuses uv's cached environment (pipx users instead run pipx upgrade und-mcp).
uvx fetches and runs the wrapper on demand, installing nothing permanent
(it is what the Quickstart uses via Claude Desktop's args).
Installing from source
If you already have a repo checkout of this project (contributors), you can instead install from source as a fallback:
# from this directory
pip install .
Configuration
Provide both your key and your API base URL — the URL is required and has no default, so a key alone will not start the wrapper. Two ways (values may also be mixed: any value that is missing or blank in the environment is read from the file):
Environment variables:
UND_API_KEY— required. Yourund_...key.UND_API_URL— required (and nonblank, well-formed). The confirmed und API host: anhttps://URL (a normal URL path is fine). For local testing only,http://is accepted only for loopback hosts (http://localhost[:PORT],http://127.0.0.1[:PORT],http://[::1][:PORT]). Non-loopbackhttp://, other schemes, embeddeduser:pass@credentials, and malformed hosts or ports are rejected with a clear error before the server starts or any request goes out.
Deliberately unsupported URL forms — three valid-but-unusual URLs are
rejected by design (safe over-strictness: rejected before the server starts,
with the same clear error that never echoes the URL): trailing-dot FQDNs (https://api.example.com.), expanded or
zero-compressed IPv6 loopback
literals other than [::1] (e.g. http://[0:0:0:0:0:0:0:1]), and
IPv4-mapped IPv6 hosts (https://[::ffff:127.0.0.1]). A raw space inside the
URL path is accepted — the HTTP client percent-encodes it.
Or a config file at ~/.config/und-mcp/config.toml:
api_url = "https://api.example.com" # required; PLACEHOLDER -- replace with the confirmed host before use
api_key = "und_..." # required
The api_url value above is an obvious placeholder (api.example.com is
a reserved domain, not a live host) — replace it with the confirmed und
API host before use.
Environment variables take precedence over the file. If a value is missing or
blank in the environment, the file is consulted as a fallback for that
value. Only when both UND_API_URL and UND_API_KEY are set to
nonblank values is the file not read at all. Only when a value is still
missing or blank after both sources are checked does the wrapper exit
with a clear error message (it never logs your key, and it never echoes the
supplied URL in an error either). A resolved URL that fails validation —
e.g. non-loopback http:// — exits with the same kind of clear error,
before the server is constructed or any request is made.
⚠️ There is no default API host, and non-local hosts must use HTTPS. The wrapper accepts
https://URLs for any host, andhttp://only for loopback hosts (localhost,127.0.0.1,[::1]). Note that HTTPS does not verify host ownership: it only proves the connection reached a host with a valid certificate for that name. Before you supply a real API key, obtain the confirmed und API host (HTTPS) from the und team and confirm it matches what you set inUND_API_URL(env orconfig.toml) — using a real key before the host is confirmed risks sending it to the wrong place. The loopbackhttp://exception is for local testing only: it works with any key, so use it against a local stand-in, never as a substitute for the confirmed host.
The config file holds a plaintext secret.
config.tomlstores your key in plaintext on disk. Keep it private: restrict its permissions (e.g.chmod 600), and never commit it, sync it to a shared or cloud location, or share it. The same care applies to any environment you export the key into.
Claude Desktop
Edit claude_desktop_config.json (on macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"und": {
"command": "und-mcp",
"env": {
"UND_API_URL": "https://api.example.com",
"UND_API_KEY": "und_..."
}
}
}
}
Both values are required — a key without UND_API_URL will not start the
server. The UND_API_URL value above is an obvious placeholder
(api.example.com is a reserved domain, not a live host) — obtain the
confirmed und API host from the und team and replace the placeholder before
using a real key.
Restart Claude Desktop. You'll see the und server and its run_test tool
available.
Claude Code
Register the stdio server. Options go before the -- separator; everything
after the -- is the command Claude Code launches (and its arguments) — not a
Claude flag:
# if installed with pipx
claude mcp add --transport stdio und-mcp -- und-mcp
# zero-install alternative (uvx fetches and runs it on demand)
claude mcp add --transport stdio und-mcp -- uvx und-mcp
Claude Code hands the server its key and API URL in one of two ways (both are required; any value that is missing or blank in the environment is read from the file):
-
Local config file (recommended). Create
~/.config/und-mcp/config.tomlwith bothapi_urlandapi_key, as shown in Configuration. The wrapper reads it automatically, so the key never appears in a shell command, your shell history, or a project file. -
Explicitly configured environment. Pass repeatable
--env KEY=VALUEflags before the--:claude mcp add --transport stdio \ --env UND_API_URL="<confirmed API host>" \ --env UND_API_KEY="<paste key here>" \ und-mcp -- und-mcp
Don't paste a real key into a shell command like this: it is stored verbatim in the saved MCP config and also remains in your shell history. If you prefer the environment, set
UND_API_URL/UND_API_KEYin your shell profile or in the environment you launch Claude Code from, and register the server with no--envflags.
Whichever way you choose, the value ends up stored in plaintext on disk (the config file, or the saved MCP config), so treat that file as a secret and keep it private.
Auditable by design
A live API key sits next to this code, so it's built to be read in a few minutes:
- stdio only — no HTTP/
servemode, no OAuth, no listening socket. - No telemetry, no background calls — the only network activity is the
explicit
GETyour tool triggers, on demand. - Read-only — no write/delete endpoints.
- Error-sanitizing — API error responses are mapped to short, actionable messages; arbitrary server error bodies are never echoed back to Claude.
- Proxy-immune — the HTTP client is built with
trust_env=False, so proxy/netrc settings in the environment cannot redirect requests. - ~150 lines of plain Python:
config.py,client.py,server.py.
SDK version note
The MCP Python SDK is in fast flux. This wrapper is pinned to mcp==2.3.0
(the v2 line, where FastMCP was renamed to MCPServer). If you upgrade the
mcp SDK or Claude and the tools stop appearing, you may need a corresponding
und-mcp bump. Keep the pinned version in pyproject.toml as your reference.
Troubleshooting
UND_API_URL is not set— the URL is required and has no default; a key alone will not start the server. Obtain the confirmed und API host from the und team, setUND_API_URL(env orapi_urlinconfig.toml), then restart Claude. For local testing, an explicit loopback HTTP URL such ashttp://127.0.0.1:PORTworks.UND_API_KEY is not set— set the key (env orconfig.toml), then restart Claude.UND_API_URL is invalid ...— the URL failed validation. Onlyhttps://is accepted for non-local hosts;http://only for loopback hosts (localhost,127.0.0.1,[::1], optional port); embeddeduser:pass@credentials and malformed hosts or ports are rejected. Set anhttps://URL to the confirmed und API host (or a loopbackhttp://URL for local testing), then restart Claude.rejected the key (401/403)from a tool — your key is invalid, revoked, or expired. Ask the und team to reissue it.Rate limited by the und API (429)...— you hit the API rate limit; if the server sent a numericRetry-After, the tool tells Claude the wait duration before retrying.- No tools listed — check the SDK version note above.
- No
undserver after restart (Quickstart) —uvxmust be findable by Claude Desktop, which does not inherit your shellPATH. Runwhich uvxand use the printed absolute path as"command". The first start also needs internet (uvxdownloads the wrapper from PyPI).
Running the tests
Install the wrapper (with the test extra) into the Python environment you
will run the tests with, then run the suite from that same environment.
Quote the editable test-extra argument so the shell does not glob .[test]:
# from this directory
python -m pip install -e '.[test]'
python -m pytest tests -q
The stdio end-to-end tests resolve the und-mcp console script from the
sysconfig scripts directory of the very Python environment running pytest
(bin on POSIX, Scripts on Windows, including the Windows .exe launcher)
and spawn it as a subprocess. There is no hard-coded venv path and no
fallback to an unrelated und-mcp on PATH: the console script must belong to
the environment running the tests. Run the suite with whichever environment has
the wrapper and its test dependencies installed, e.g. from the repository root:
env PYTHONDONTWRITEBYTECODE=1 wrapper/.venv/bin/python -m pytest -q -p no:cacheprovider wrapper/tests
If und-mcp is not installed in the environment that runs the tests, the
suite fails up front with a clear, actionable error telling you to install it
(python -m pip install -e '.[test]'), instead of a confusing spawn error
mid-test.
The suite drives the real entry point over an actual stdio channel against an
ephemeral 127.0.0.1 HTTP server, with a synthetic key — no real API, no
network access beyond loopback.
Metadata
Release files for und-mcp 0.1.1
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 |
|---|---|---|---|---|
| und_mcp-0.1.1.tar.gz | 30.3 kB | Without provenance | Details for und_mcp-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| und_mcp-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for und_mcp-0.1.1-py3-none-any.whl |
Total release size: 46.9 kB
Release files / und_mcp-0.1.1.tar.gz
| Download URL | und_mcp-0.1.1.tar.gz |
|---|---|
| Size | 30.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f598aa79e780e5d890427e7748635c0bc51c5762d30d76d99b64fbe42e15430
|
|
BLAKE2b-256 checksum How to use checksums |
c686d4f30799833849084f312508e026ed8e9857da2b42ef9ace4e28e27018fb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.0
|
Release files / und_mcp-0.1.1-py3-none-any.whl
| Download URL | und_mcp-0.1.1-py3-none-any.whl |
|---|---|
| Size | 16.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6b7612853a1b71222f3e19b2870a1096fb0cf4c660375b2ec5aab6fcb4e2a496
|
|
BLAKE2b-256 checksum How to use checksums |
7fe4fd72575914c8955380ead9ab70ec5b6b2460662575108035b0bfd2e15a99
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.15.0
|
Security for und-mcp 0.1.1
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.