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

@cyanheads/iana-registries-mcp-server

Look up IANA ports, media types, HTTP status codes and fields, URI schemes, enterprise numbers, and BCP 47 language tags; check RFC status; search and read any IANA registry via MCP. STDIO or Streamable HTTP.

10 Tools

Public Hosted Server: https://iana-registries.caseyjhand.com/mcp

Overview

Official IANA protocol registries plus RFC and Internet-Draft status. Look up ports, media types, HTTP status codes and headers, URI schemes, enterprise numbers, and language tags; search any other registry; and check whether an RFC is current, obsoleted, or updated. No API key required.

Tools

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
• keyword matches registered type names and status annotations, never file extensions; a one-word keyword shaped like an extension (jpg, .mp3, *.jpg) gets a notice saying so, unless a registered top-level type or subtype is named that word (png stays quiet: image/png exists)
• 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 when the template has them; template.fetched is false when the template can't be read, and template.available is false when IANA publishes no template for the type (image/gif, text/plain)

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
• Canonicalization keeps variant order while deduplicating preferred-value collisions; the registered ja-Latn-hepburn-heploc context becomes ja-Latn-alalc97, preserving unrelated parts
• Extension parts add extension allocation (allocated, unallocated, or unavailable), descriptions, defining RFCs, and organization authority; extension_source records the copy used. Allocation does not change base validity or validate extension content. Optional allocation reads stop within 3 seconds; failure returns base analysis with retry guidance, or a stale allocation copy marked as such

iana_get_rfc_status tool

• Up to 1,000 normalized nonblank ids, canonically deduplicated before selecting ten per call: RFC numbers in any common form; BCP, STD, and FYI numbers (BCP 14); draft names with or without a revision suffix; RFC and draft file names (rfc2616.txt, draft-ietf-httpbis-semantics-19.txt); the URL of an RFC or draft on datatracker.ietf.org, tools.ietf.org, or ietf.org, or of an RFC on rfc-editor.org (https://tools.ietf.org/html/rfc7231); and a series URL at rfc-editor.org/info/ or datatracker.ietf.org/doc/ (https://datatracker.ietf.org/doc/bcp14/). A URL's query and fragment are dropped
• total_ids counts distinct ids; deferred_ids previews the next ten, while deferred_count counts the whole remainder. Resubmit the same original ids with next_ids_offset as ids_offset to continue. deferred_reason: "batch_limit" and deferred_guidance explain the cut; at/past-end offsets return an empty page without upstream requests
• documents[] gives RFCs their current and as-published status, stream, group, obsoletes and updates relations, the series they belong to (is_also), and errata page; gives drafts their state, IESG state, replacements, and became_rfc; and gives a series its member RFCs (kind: "series"). An unknown id is found: false with guidance, and a draft revision past the latest stays found with guidance naming the latest
• An id whose lookup fails lands in failed[] while the rest still answer, with its reason and, when the failure states it, retryable (false when calling again fails the same way); the call fails only when every id failed. A call starts at most 20 Datatracker requests (an RFC or a series takes 1, plus 1 per call for the RFCs' series; a draft 3, or 4 with a revision suffix); ids past that come back in failed[] with reason request_limit, to resubmit

iana_search_registries tool

• query words matched against registry titles, categories, and ids, singular and plural alike (ethertype finds "Ethertypes"); every word must match, for and the included; limit accepts 1–1,000,000 and clamps to 50, default 15, paged by offset
• A registry or sub-registry id given exactly ranks first, as does a registry id given as words (protocol numbers → protocol-numbers); the closest titles follow
• A registry listed under several protocol categories comes back once, its categories joined with ;
• 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, or on the column field names) and contains (words in any field, records with an equal field first)
• value digits compare exactly with a cell of digits (0443 finds 443) or a decimal range, including 64-bit endpoints. One 0x token compares by number with a one-token 0x cell (0x5 finds 0x05) or a hex range; other 0x forms compare their digits as written, in any comma, space, or brace spelling
• A value that misses names the other columns holding it, with their row counts, so field recovers a lookup by mnemonic or service name; a hit says when rows without a key cell hold the value too
• Pages by cursor / next_cursor (pages after the first carry offset) within the effective limit (at most 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; a table that nests tables lists them in subregistries[] on its first page, and a sub-registry read carries the registry's own notes and footnotes in registry_notes[]
• Failures carry unknown_registry, unknown_subregistry, unknown_field, 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
• Registries load on first use and stay cached for 24 hours before revalidating; when a refresh fails, a cached copy up to 7 days old answers with source.stale: true
• Per-host request pacing (iana.org, rfc-editor.org, datatracker.ietf.org) and one 45-second budget per tool call covering every retry and queue wait
• Generic records keep the registry's XML element names as field names (rec is the Recommended column)
• Contact, designated-expert, and registrant-person fields are dropped, and email addresses in free text become [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; positive safe-integer limit values up to 1,000,000 clamp to 100 (default 25), or 50 for iana_search_registries (default 15). Clamped calls disclose requested_limit and effective_limit on both surfaces, including exact and empty modes. List modes (keyword, organization, description) page with offset and return next_offset, totalCount, shown, and truncated
• Provenance on every registry response: source carries the registry file, registry_updated, 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

Public Hosted Instance

A public instance is available at https://iana-registries.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "iana-registries-mcp-server": {
      "type": "streamable-http",
      "url": "https://iana-registries.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

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 bunx @cyanheads/iana-registries-mcp-server@latest
# 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

1. Navigate into the directory:

cd iana-registries-mcp-server

1. Install dependencies:

bun install

1. 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:

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

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.