Skip to main content

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 or rep. 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 via UND_API_URL or config.toml before 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. Your und_... key.
  • UND_API_URL — required (and nonblank, well-formed). The confirmed und API host: an https:// 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-loopback http://, other schemes, embedded user: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, and http:// 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 in UND_API_URL (env or config.toml) — using a real key before the host is confirmed risks sending it to the wrong place. The loopback http:// 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.toml stores 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.toml with both api_url and api_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=VALUE flags 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_KEY in your shell profile or in the environment you launch Claude Code from, and register the server with no --env flags.

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/serve mode, no OAuth, no listening socket.
  • No telemetry, no background calls — the only network activity is the explicit GET your 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, set UND_API_URL (env or api_url in config.toml), then restart Claude. For local testing, an explicit loopback HTTP URL such as http://127.0.0.1:PORT works.
  • UND_API_KEY is not set — set the key (env or config.toml), then restart Claude.
  • UND_API_URL is invalid ... — the URL failed validation. Only https:// is accepted for non-local hosts; http:// only for loopback hosts (localhost, 127.0.0.1, [::1], optional port); embedded user:pass@ credentials and malformed hosts or ports are rejected. Set an https:// URL to the confirmed und API host (or a loopback http:// 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 numeric Retry-After, the tool tells Claude the wait duration before retrying.
  • No tools listed — check the SDK version note above.
  • No und server after restart (Quickstart) — uvx must be findable by Claude Desktop, which does not inherit your shell PATH. Run which uvx and use the printed absolute path as "command". The first start also needs internet (uvx downloads 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)

Source distribution for und-mcp 0.1.1
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)

Table of built distributions (wheels) for und-mcp 0.1.1
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page