Toolkit MCP Server

@cyanheads/toolkit-mcp-server Generate random IDs, QR codes, and hashes, encode and decode values, and geolocate IPs, plus gated network and system diagnostics, via MCP. STDIO or Streamable HTTP. 7 Tools • 1 Skill

Public Hosted Server: https://toolkit.caseyjhand.com/mcp

Overview

Everyday developer utilities: generate IDs, QR codes, and hashes, encode and decode values, and geolocate a public IP or hostname. Only the geolocation lookup and the gated network diagnostics (off by default) make network calls; everything else runs locally.

Tools

Skill

MCP clients that support the Skills extension read it as skill://toolkit-guide/SKILL.md. Plugin installs load it from skills/, which also ships in the npm package, the Docker image, and the .mcpb bundle.

Capability reference

toolkit_hash_value tool

• value read per inputEncoding (utf8 default, hex, base64); algorithm is sha256 (default), sha384, or sha512, with sha1 and md5 for checksum compatibility and verifying existing HMAC-SHA1 signatures only; operation is generate or compare, and when omitted it compares if expected is sent
• A non-empty secret makes the digest an HMAC keyed by it, for webhook signatures (GitHub's X-Hub-Signature-256 pastes into expected as-is) and HS256 JWT signatures; secretEncoding is utf8 (default), hex, base64, or base64url (a JWK k). The result then carries hmac: true, and the secret is never echoed in the result or an error; a secret invalid for its encoding fails as invalid_secret_encoding
• generate returns digest in digestEncoding (hex default, base64, unpadded base64url, or sri for plain SHA-2 digests, where an HMAC fails as sri_with_secret) plus lengthInBytes; compare returns matches against expected, pasted as published: hex, base64, or base64url, bare or prefixed (sha256: , sha256= ); SRI, including a multi-entry npm integrity value; or one checksum-file line as sha256sum, shasum, md5, or openssl dgst prints it
• A bad expected fails as expected_malformed (including a whole multi-line checksum file, with a hint to pass the file's own line), expected_length_mismatch (the hint names the algorithm that length fits), or expected_algorithm_mismatch (a tag, prefix, or SRI entry naming another algorithm)

toolkit_generate_id tool

• type is uuid_v4 (default), uuid_v7, or ulid; count is 1–1000 (default 1)
• ids always holds exactly count values; uuid_v7 and ulid batches are strictly increasing even within one millisecond, with random gaps so no id is derivable from another

toolkit_generate_qr tool

• data up to 2953 UTF-8 bytes at errorCorrection L, less at M (default), Q, and H; format is svg (default), png_base64, or terminal; margin 0–20 modules (default 4), scale 1–32 px per module (default 4)
• Returns content, the symbol version (1–40), mimeType for image formats, and byteLength for PNG; png_base64 also arrives as an MCP image block, and terminal is plain Unicode half-blocks drawn for a dark background
• Over-capacity input fails as data_too_large with its byte count; a PNG over 2048 px per side fails as raster_too_large with a scale that fits, while svg and terminal have no pixel cap

toolkit_encode_value tool

• operation (encode or decode) and encoding (base64, base64url, hex, url) are required; whitespace in hex, base64, and base64url input is ignored, so wrapped MIME and PEM bodies decode as-is
• Decode returns result as utf8 text unless outputEncoding asks for hex, base64, or unpadded base64url, which returns the bytes losslessly and transcodes between encodings; malformed input fails as decode_failed, and binary bytes as decode_not_utf8 rather than with replacement characters

toolkit_geolocate_ip tool

• target is an IPv4/IPv6 address or a dotted hostname, DNS-resolved first; private or reserved addresses, and public-format ones the provider reports as unlocatable, fail as private_target, unresolvable hostnames as unresolvable_host
• Or send targets (up to 1000) instead, never both: the first 100 return ordered results with per-target errors, failedCount counts failures, and unprocessedTargets lists the rest to resubmit
• Returns country, countryCode, region, city, latitude/longitude, asn, asHolder, asName, org, isp, and timezone with resolvedIp and source; a true in proxy, hosting, or mobile means the location describes infrastructure, not a person
• org can name a customer or sub-allocation (APNIC and Cloudflare DNS Resolver project for 1.1.1.1); isp, asHolder, and asName (CLOUDFLARENET) name the network operator. With no org from the provider, org carries asHolder, then isp
• Uses the keyless ip-api free tier over plaintext HTTP by default (TOOLKIT_GEO_BASE_URL, TOOLKIT_GEO_API_KEY); results are cached per resolved IP
• Single and batch lookups have separate rate limits (TOOLKIT_GEO_RATE_LIMIT_PER_MIN=45, TOOLKIT_GEO_BATCH_RATE_LIMIT_PER_MIN=15); refusals report rate_limited with seconds to wait, and cache hits stay free

toolkit_check_network tool

• mode is ping, traceroute, connectivity, or public_ip (the host's IPv4 egress address; it can't show whether IPv6 egress works); target is required except for public_ip, and port (1–65535) for connectivity; count 1–10 pings (default 3), timeoutMs 100–30000 (default 3000, one budget across every address for connectivity); family 4 or 6 probes one address family
• A hostname resolves once to all its addresses, tried in turn and alternating IPv4 and IPv6 until one gives a result; resolvedIp names the address whose result is reported
• A silent host is reachable: false, not an error; ping adds rttMs, sent, received, and packetLossPercent, connectivity adds outcome (open, refused, timeout, unreachable), and traceroute returns hops; a hostname that won't resolve fails as unreachable in every mode, as does ping or traceroute when its binary gives no result for any address tried (missing, stopped at its time limit, or exited with an error), and a family the target has no address in fails as family_mismatch
• Registered only when TOOLKIT_ENABLE_NET_DIAGNOSTICS=true; unless TOOLKIT_ALLOW_PRIVATE_NETWORK=true, a hostname's private and reserved addresses are skipped, a target with nothing else fails as private_target_blocked, and error messages count those addresses instead of naming them

toolkit_check_system tool

• what is os, cpu, memory, load, or interfaces; exactly one matching facet object is populated
• os names the runtime (runtime is bun or node, runtimeVersion its version) beside nodeVersion, the Node.js version the process reports
• memory.availableBytes is the allocation headroom, the same figure under Bun and Node, and limitBytes appears under a container memory limit; totalBytes, freeBytes, and usedBytes are raw OS figures, and on macOS freeBytes is free pages alone, so usedBytes counts reclaimable cache as used there
• Under Bun on macOS the headroom is read from the host's page statistics; when they can't be read the call fails as memory_stats_unavailable instead of reporting free pages
• Registered only when TOOLKIT_ENABLE_SYSTEM_INFO=true, since os and interfaces disclose host topology and version details

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Toolkit-specific:

• Hashing, ID minting, QR encoding, and encode/decode run in-process on node:crypto, Buffer, and the qrcode library, with no upstream calls
• Geolocation calls the provider, never the target, and checks the DNS-resolved IP against private ranges, so a hostname can't reach an internal address
• Fail-closed gating: toolkit_check_network and toolkit_check_system are absent from tools/list unless enabled. Both report on the server's host, not the caller's, so they belong on local or self-hosted deployments
• Two-tier network gate: with diagnostics on, private, loopback, link-local, and reserved targets (the cloud-metadata endpoint included) stay blocked unti