
iana-registries-mcp-server
io.github.cyanheads/iana-registries-mcp-server
Find IANA ports, MIME types, HTTP codes/fields, URI schemes, PENs, BCP 47 tags, RFCs, any registry.
Documentation
@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.
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
| 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, Internet-Drafts, or BCP/STD/FYI series 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), orkeyword;transport(tcp,udp,sctp,dccp) filters every mode - Each row carries
state(assigned,reserved,unassigned,unnamed) and its transport; port mode addsport_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) orkeyword;top_levelnarrows keyword mode keywordmatches 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 (pngstays quiet:image/pngexists)statusiscurrent,deprecated, orobsoleted, withreplaced_bywhen the registry names a replacementtypemode also reads the registration template and returns its file-extension, intended-usage, and deprecated-alias statements undertemplatewhen the template has them;template.fetchedisfalsewhen the template can't be read, andtemplate.availableisfalsewhen IANA publishes no template for the type (image/gif,text/plain)
iana_lookup_http_status tool
- One of
code(100–599) orkeywordover registered reason phrases - Returns
classandstate(assigned,temporary,obsoleted,unused) with the defining reference and section; an unassigned code returnsfound: falseand itsunassigned_range
iana_lookup_http_field tool
- One of
name(case-insensitive) orkeywordover names and comments;statusfilters both modes - Returns
status(permanent,provisional,deprecated,obsoleted),structured_typewhen one is registered, comments, and the defining reference
iana_lookup_uri_scheme tool
- One of
scheme(a trailing:or://is ignored) orkeyword;status(permanent,provisional,historical) filters both modes - Returns the description, references,
well_known_uri_support, andtemplate_urlwhen a registration template is published
iana_lookup_pen tool
- One of
pen(a number, or an OID under1.3.6.1.4.1) ororganizationwords; OIDs accept a leading dot and case-insensitiveiso.3.6.1.4.1,iso.org.dod.internet.private.enterprise(s),SNMPv2-SMI::enterprises, orenterprisesprefixes - Each entry carries its
oidprefix andstate(assigned,reserved,unassigned); wholeReserved,Unassigned, and---none---markers are case-insensitive.organization_withheld: truemarks an organization line held back because it mixes in contact details - An OID with arcs below the enterprise number echoes
requested_oidandsub_arcs; those arcs are assigned by the enterprise, not IANA - A non-enterprise OID or the bare enterprise arc fails before fetching, with guidance to discover SMI tables through
iana_search_registries(query: "smi")
iana_lookup_language_tag tool
- One of
tag(underscores read as hyphens) ordescription;subtag_typenarrows description mode - Tag mode returns
well_formed,valid,canonical_tag(valid tags only), each part insubtags[], andissues[]:kindunknownandwrong_positionmake a tag invalid, whiledeprecated,variant_prefix_mismatch,suppress_script_redundant, andextension_not_validatedare 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-heploccontext becomesja-Latn-alalc97, preserving unrelated parts - Extension parts add
extensionallocation (allocated,unallocated, orunavailable), descriptions, defining RFCs, and organization authority;extension_sourcerecords 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 - Citation forms include
[RFC9110],[I-D.ietf-tls-esni],RFC 9110, Section 15.5.5, RFC DOIs (10.17487/RFC9110,doi:…, orhttps://doi.org/…), and RFC Editor/errata/rfcNURLs. Sections are ignored with a notice: the result describes the document, never section or errata contents total_idscounts distinct full requests after syntactic aliases merge; unsuffixed and revision-qualified drafts remain distinct, even when the requested revision is current.deferred_idspreviews the next ten, whiledeferred_countcounts the whole remainder. Resubmit the same originalidswithnext_ids_offsetasids_offsetto continue; at/past-end offsets return an empty page without upstream requestsdocuments[]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, andbecame_rfc; and gives a series its member RFCs (kind: "series"). An unknown id isfound: falsewithguidance, and a draft revision past the latest stays found withguidancenaming the latest- An id whose lookup fails lands in
failed[]while the rest still answer, with itsreasonand, when the failure states it,retryable(falsewhen 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 infailed[]with reasonrequest_limit, to resubmit
iana_search_registries tool
querywords matched against registry titles, categories, and ids, singular and plural alike (ethertypefinds "Ethertypes"); every word must match,forandtheincluded;limitaccepts 1–1,000,000 and clamps to 50, default 15, paged byoffset- 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_idandsubregistry_idthatiana_get_registry_recordsreads, plus registration procedure, defining documents, and page and XML URLs
iana_get_registry_records tool
- A
registryid oriana.org/assignmentsURL, optionalsubregistry, and filtersvalue(exact match on the key column, or on the columnfieldnames) andcontains(words in any field, records with an equal field first) valuesupports exact integers, inclusive signed decimal ranges (a-b,a to b), and strictless than/greater thanbounds without precision loss. A single0xtoken also compares with decimal cells and established bare-hex columns (EtherTypetype_hex, PPP protocolvalue); bare decimal input never gains hexadecimal meaning- Hex byte sequences preserve width across compact, comma, space, and brace forms, including TLS byte ranges and wildcards:
0x0013matches0x00,0x13, while0x13does not. An implicit key's range-only match yields to an exact alternate-column hit by returning a miss with afieldhint; explicitfieldselection stays authoritative - A
valuethat misses names the other columns holding it, with their row counts, sofieldrecovers a lookup by mnemonic or service name; a hit says when rows without a key cell hold the value too - Pages whole records by
cursor/next_cursor(pages after the first carryoffset) within the effectivelimit(at most 100, default 25); field text and metadata lists are returned whole, preserving paragraph boundaries and artwork spacing - A registry with several sub-registries and none chosen returns
subregistries[]instead of records; a table that nests tables lists them insubregistries[]on its first page, and a sub-registry read carries the registry's own notes and footnotes inregistry_notes[] - Failures carry
unknown_registry,unknown_subregistry,unknown_field,non_xml_registry,invalid_cursor, orcursor_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 (
recis 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: falsewith anoticenaming the next step, an unknown RFC or draft returnsfound: falsewithguidance, and an invalid language tag returnsvalid: falsewith itsissues[]. 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_requiredotherwise; positive safe-integerlimitvalues up to 1,000,000 clamp to 100 (default 25), or 50 foriana_search_registries(default 15). Clamped calls discloserequested_limitandeffective_limiton both surfaces, including exact and empty modes. List modes (keyword,organization,description) page withoffsetand returnnext_offset,totalCount,shown, andtruncated - List-mode
founddescribes the full match set, even on an empty past-end page; port searches require a named service after transport filtering, and PEN organization searches require an assigned entry - Provenance on every registry response:
sourcecarries the registry file,registry_updated,fetched_at, andstale - Typed failures with recovery hints: every tool declares
upstream_unreadable(index_unreadablefor search) andpacer_shed, which carriesretryAfterwhen this server's own request queue is full
Getting started
Connect to the hosted instance, no install:
claude mcp add --transport http iana-registries-mcp-server https://iana-registries.caseyjhand.com/mcp
Or run it locally:
claude mcp add iana-registries-mcp-server -- npx -y @cyanheads/iana-registries-mcp-server
For other clients, add this to the MCP config file:
{
"mcpServers": {
"iana-registries-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/iana-registries-mcp-server"]
}
}
}
No API key is required. For Docker or a source build, see Running the server.
Agent skill
The iana-registries-guide chains registry assignments to their defining documents, current RFC relationships, and standards-series membership. It ships with plugin installs, npm, Docker, and the MCPB bundle, and is available over MCP to clients supporting the Skills extension.
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
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
- Clone the repository:
git clone https://github.com/cyanheads/iana-registries-mcp-server.git
- Navigate into the directory:
cd iana-registries-mcp-server
- Install dependencies:
bun install
- Configure environment (optional):
cp .env.example .env
# the server needs no variables of its own; edit framework overrides as needed
Docker and HTTP
Run the published image:
{
"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
# Server listens at http://localhost:3010/mcp
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, language subtag and extension registries, the protocol index and its ranked search, 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/catchin tool logic - Use
ctx.logfor logging; registry text is third-party, soformat()renders it through thequote()andinline()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.
@cyanheads/iana-registries-mcp-servernpm install @cyanheads/iana-registries-mcp-server@cyanheads/iana-registries-mcp-servernpm install @cyanheads/iana-registries-mcp-serverRemote
Related Servers
io.github.cyanheads/anime-mcp-server
Search anime/manga, franchise relations, schedule, characters, rankings, studio filmography.
io.github.cyanheads/art-institute-chicago-mcp-server
Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides.
io.github.cyanheads/arxiv-mcp-server
Search arXiv, fetch paper metadata, and read full-text content.