@cyanheads/iana-registries-mcp-server
by cyanheads
README.md
<div align="center">
<h1>@cyanheads/iana-registries-mcp-server</h1>
<p><b>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.</b>
<div>10 Tools • 1 Skill</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/iana-registries-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/iana-registries-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/iana-registries-mcp-server/releases/latest/download/iana-registries-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=iana-registries-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvaWFuYS1yZWdpc3RyaWVzLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22iana-registries-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fiana-registries-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**Public Hosted Server:** [https://iana-registries.caseyjhand.com/mcp](https://iana-registries.caseyjhand.com/mcp)
</div>
---
## 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` <sub>tool</sub>
- 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` <sub>tool</sub>
- 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` <sub>tool</sub>
- 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` <sub>tool</sub>
- 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` <sub>tool</sub>
- 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` <sub>tool</sub>
- One of `pen` (a number, or an OID under `1.3.6.1.4.1`) or `organization` words; OIDs accept a leading dot and case-insensitive `iso.3.6.1.4.1`, `iso.org.dod.internet.private.enterprise(s)`, `SNMPv2-SMI::enterprises`, or `enterprises` prefixes
- Each entry carries its `oid` prefix and `state` (`assigned`, `reserved`, `unassigned`); whole `Reserved`, `Unassigned`, and `---none---` markers are case-insensitive. `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
- 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` <sub>tool</sub>
- 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` <sub>tool</sub>
- 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:…`, or `https://doi.org/…`), and RFC Editor `/errata/rfcN` URLs. Sections are ignored with a notice: the result describes the document, never section or errata contents
- `total_ids` counts distinct full requests after syntactic aliases merge; unsuffixed and revision-qualified drafts remain distinct, even when the requested revision is current. `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; 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` <sub>tool</sub>
- `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` <sub>tool</sub>
- 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` supports exact integers, inclusive signed decimal ranges (`a-b`, `a to b`), and strict `less than` / `greater than` bounds without precision loss. A single `0x` token also compares with decimal cells and established bare-hex columns (EtherType `type_hex`, PPP protocol `value`); 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: `0x0013` matches `0x00,0x13`, while `0x13` does not. An implicit key's range-only match yields to an exact alternate-column hit by returning a miss with a `field` hint; explicit `field` selection stays authoritative
- 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 whole records by `cursor` / `next_cursor` (pages after the first carry `offset`) within the effective `limit` (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 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`](https://github.com/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`
- List-mode `found` describes 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: `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
Connect to the hosted instance, no install:
```sh
claude mcp add --transport http iana-registries-mcp-server https://iana-registries.caseyjhand.com/mcp
```
Or run it locally:
```sh
claude mcp add iana-registries-mcp-server -- npx -y @cyanheads/iana-registries-mcp-server
```
For other clients, add this to the MCP config file:
```json
{
"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](#running-the-server).
## Agent skill
The [iana-registries-guide](./skills/iana-registries-guide/SKILL.md) 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](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
See [`.env.example`](./.env.example) for the full list of framework overrides.
## Running the server
### Prerequisites
- [Bun v1.4.0](https://bun.sh/) 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:**
```sh
git clone https://github.com/cyanheads/iana-registries-mcp-server.git
```
2. **Navigate into the directory:**
```sh
cd iana-registries-mcp-server
```
3. **Install dependencies:**
```sh
bun install
```
4. **Configure environment (optional):**
```sh
cp .env.example .env
# the server needs no variables of its own; edit framework overrides as needed
```
### Docker and HTTP
Run the published image:
```json
{
"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:
```sh
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**:
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:http
# or
bun run start:stdio
```
- **Run checks and tests**:
```sh
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`](./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:
```sh
bun run devcheck
bun run test
```
## License
This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.
IANA and the IETF Trust dedicate the protocol registries to the public domain under CC0 1.0 ([licensing terms](https://www.iana.org/help/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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues