io.github.cyanheads/iana-registries-mcp-server

---

Overview

Protocol parameters from the IANA registries, and document status from the RFC Editor and the IETF Datatracker. Look up ports, media types, HTTP status codes and fields, URI schemes, Private Enterprise Numbers, and BCP 47 language tags; check whether an RFC is current, obsoleted, or updated, and where an Internet-Draft stands; and search and read any other registry in the IANA protocol index. RFC answers are metadata only: the server never returns RFC text. Runs as a stdio process or a local Streamable HTTP server.

Tools

Tool	Description
iana_lookup_port	Service name and port assignments by port number, service name, or keyword, per transport, with the port's RFC 6335 class
iana_lookup_media_type	Registered media (MIME) types by exact type or keyword, with status, replacement, and registration-template statements
iana_lookup_http_status	An HTTP status code by number, or reason phrases by keyword; an unassigned code reports its range
iana_lookup_http_field	Registered HTTP field (header and trailer) names with status and Structured Field type
iana_lookup_uri_scheme	Registered URI schemes with status, description, and well-known URI support
iana_lookup_pen	Private Enterprise Numbers by number or OID under 1.3.6.1.4.1, or by organization name
iana_lookup_language_tag	Validate and canonicalize a BCP 47 language tag subtag by subtag, or search subtags by description
iana_get_rfc_status	Current status and relations of up to 10 RFCs or Internet-Drafts per call
iana_search_registries	Find any registry or sub-registry in the IANA protocol index by keyword
iana_get_registry_records	Read and filter the records of any IANA XML registry by id

Capability reference

iana_lookup_port _tool

• One of port (0–65535), service (exact name), or keyword; transport (tcp, udp, sctp, dccp) filters every mode
• Each row carries state (assigned, reserved, unassigned, unnamed) and its transport; port mode adds port_class (system, user, dynamic) and the range rows that contain the port

---

iana_lookup_media_type _tool

• One of type (e.g. application/json; parameters after ; are dropped) or keyword; top_level narrows keyword mode
• status is current, deprecated, or obsoleted, with replaced_by when the registry names a replacement
• type mode also reads the registration template and returns its file-extension, intended-usage, and deprecated-alias statements under template; template.fetched is false when the template can't be read

---

iana_lookup_http_status _tool

• One of code (100–599) or keyword over registered reason phrases
• Returns class and state (assigned, temporary, obsoleted, unused) with the defining reference and section; an unassigned code returns found: false and its unassigned_range

---

iana_lookup_http_field _tool

• One of name (case-insensitive) or keyword over names and comments; status filters both modes
• Returns status (permanent, provisional, deprecated, obsoleted), structured_type when one is registered, comments, and the defining reference

---

iana_lookup_uri_scheme _tool

• One of scheme (a trailing : or :// is ignored) or keyword; status (permanent, provisional, historical) filters both modes
• Returns the description, references, well_known_uri_support, and template_url when a registration template is published

---

iana_lookup_pen _tool

• One of pen (a number, or an OID under 1.3.6.1.4.1) or organization words
• Each entry carries its oid prefix and state (assigned, reserved, unassigned); organization_withheld: true marks an organization line held back because it mixes in contact details
• An OID with arcs below the enterprise number echoes requested_oid and sub_arcs; those arcs are assigned by the enterprise, not IANA

---

iana_lookup_language_tag _tool

• One of tag (underscores read as hyphens) or description; subtag_type narrows description mode
• Tag mode returns well_formed, valid, canonical_tag (valid tags only), each part in subtags[], and issues[]: kind unknown and wrong_position make a tag invalid, while deprecated, variant_prefix_mismatch, suppress_script_redundant, and extension_not_validated are advisory
• A single-subtag input lists records of other types under the same subtag in also_registered_as

---

iana_get_rfc_status _tool

• Up to 10 ids per call: RFC numbers in any common form, RFC Editor or Datatracker URLs, and draft names with or without a revision suffix; BCP, STD, and FYI numbers come back as kind: "unsupported"
• documents[] gives RFCs their current and as-published status, stream, group, obsoletes and updates relations, and errata page, and gives drafts their state, IESG state, replacements, and became_rfc; an unknown id is found: false with guidance
• An id whose upstream lookup fails lands in failed[] while the rest still answer; the call fails only when every id failed

---

iana_search_registries _tool

• query words matched against registry titles, categories, and ids, with an exact registry or sub-registry id ranked first; limit 1–50, default 15, paged by offset
• Each entry carries the registry_id and subregistry_id that iana_get_registry_records reads, plus registration procedure, defining documents, and page and XML URLs

---

iana_get_registry_records _tool

• A registry id or iana.org/assignments URL, optional subregistry, and filters value (exact match on the key column; a decimal also matches range rows) and contains (words in any field)
• Pages by cursor / next_cursor within limit (1–100, default 25) and a 48,000-character records budget; a field over 2,000 characters is cut, a record keeps at most 16 fields, and cut_fields names what was cut
• A registry with several sub-registries and none chosen returns subregistries[] instead of records; failures carry unknown_registry, unknown_subregistry, non_xml_registry, invalid_cursor, or cursor_mismatch

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.

IANA-specific:

• Live, keyless reads of the IANA registry files, the RFC Editor's per-RFC JSON, and the IETF Datatracker
• Each registry loads on first use and stays cached for 24 hours before revalidating; when a refresh fails, a cached copy up to 7 days old answers with source.stale: true
• Self-imposed request pacing per host (iana.org, rfc-editor.org, datatracker.ietf.org) and one 45-second budget per tool call that covers every retry and queue wait
• Generic records keep the registry's XML element names as field names (rec is the Recommended column); the registry notes returned on the first page usually explain them
• Contact, designated-expert, and registrant-person fields are dropped by design, and email addresses in free text are replaced with [email removed]

Agent-friendly output:

• Misses are results, not errors: a lookup that finds nothing returns found: false with a notice naming the next step, an unknown RFC or draft returns found: false with guidance, and an invalid language tag returns valid: false with its issues[]. A miss means IANA has no registration, not that a value is unused in practice
• Uniform lookup contract: every lookup takes exactly one mode key and fails mode_required otherwise; limit is 1–100, default 25, and the list modes (keyword, organization, description) page with offset and return next_offset, alongside totalCount, shown, and truncated
• Provenance on every registry response: source names the registry file, registry_updated (the registry's own last-updated date), fetched_at, and stale
• Typed failures with recovery hints: every tool declares upstream_unreadable (index_unreadable for search) and pacer_shed, which carries retryAfter when this server's own request queue is full

Getting started

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "iana-registries-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/iana-registries-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "iana-registries-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/iana-registries-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "iana-registries-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/iana-registries-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API key or account: IANA, the RFC Editor, and the IETF Datatracker are all keyless.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/iana-registries-mcp-server.git

2. Navigate into the directory:

cd iana-registries-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# the server needs no variables of its own; edit framework overrides as needed

Configuration

The server reads no environment variables of its own. These framework settings apply:

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	HTTP server port.	3010
MCP_HTTP_HOST	HTTP server host.	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP endpoint path.	/mcp
MCP_SESSION_MODE	HTTP session mode: stateless, stateful, or auto.	stateless
MCP_AUTH_MODE	Authentication: none, jwt, or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.).	info
LOGS_DIR	Directory for log files (Node.js only).	<app-root>/logs
STORAGE_PROVIDER_TYPE	Storage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.	in-memory
OTEL_ENABLED	Enable OpenTelemetry.	false

See .env.example for the full list of framework overrides.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Project structure

Directory	Purpose
src/index.ts	createApp() entry point: registers the tools and starts and stops the services.
src/mcp-server/tools/definitions	Tool definitions (*.tool.ts), ten tools.
src/mcp-server/tools/shared	Schemas, list paging and notices, and markdown helpers the tools share.
src/services/upstream	Paced, budgeted HTTP client for iana.org, rfc-editor.org, and datatracker.ietf.org.
src/services/registry	Registry cache and parsers: XML registries, the PEN list, the language subtag registry, the protocol index, BCP 47 tag analysis, and personal-data scrubbing.
src/services/media-template	Media type registration template reader.
src/services/ietf	RFC Editor and Datatracker document status.
tests/	Unit and tool tests, mirroring the src/ structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging; registry text is third-party, so format() renders it through the quote() and inline() helpers
• Register new tools in the barrel at src/mcp-server/tools/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

IANA and the IETF Trust dedicate the protocol registries to the public domain under CC0 1.0 (licensing terms, joint statement of 10 November 2021). RFC documents are excluded from that statement; this server returns RFC metadata only, never RFC text. This project is independent of IANA, the IETF, and the RFC Editor.