hn-mcp-server

Hn Get Stories

hn_get_stories

Read-only

Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count for each story.

Input Schema

TableJSON Schema

Name	Required	Description
`feed`	Yes	Which HN feed to fetch. "top" includes jobs. "ask" and "show" are Ask HN / Show HN posts.
`count`	No	Number of stories to return. Larger counts take longer.
`offset`	No	Number of stories to skip from the start of the feed. Use with count for pagination.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The count cap that was applied.
`feed`	No	Which feed was fetched.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of stories returned on this page.
`total`	No	Total items in the feed (up to 500 for top/new/best, 200 for ask/show/jobs).
`notice`	No	Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result with no failed IDs.
`offset`	No	Offset that was applied to this page.
`hasMore`	No	Whether more stories are available beyond this page.
`stories`	No	Stories from the feed, ordered by HN ranking.
`failedIds`	No	IDs on this page whose fetch failed after retries. They are not deleted or missing and may load on a later call: retry the page with the same offset, or pass an ID to hn_get_thread to fetch that story alone. Absent when every item on the page loaded.
`truncated`	No	True when more stories remain beyond this page (hasMore). Absent on the last page of the feed.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedSep 24, 2026

addedOutput schema / properties / failedIds

Added value: +{
+  "description": "IDs on this page whose fetch failed after retries. They are not deleted or missing and may load on a later call: retry the page with the same offset, or pass an ID to hn_get_thread to fetch that story alone. Absent when every item on the page loaded.",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

changedOutput schema / properties / notice / description

Previous value: -"Agent guidance: the offset to pass for the next page while more stories remain, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result."New value: +"Agent guidance: the offset to pass for the next page while more stories remain, the IDs that failed to load and how to retry them, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result with no failed IDs."

Changed2 schema fields changedSep 24, 2026

changedOutput schema / properties / notice / description

Previous value: -"Recovery hint when a page is empty — e.g. offset past end of feed or feed has no items. Absent on non-empty result pages."New value: +"Agent guidance: the offset to pass for the next page while more stories remain, or why a page came back empty — offset past the end of the feed, an empty feed, or every item on the page deleted or flagged. Absent on the last page of a non-empty result."

changedOutput schema / properties / truncated / description

Previous value: -"True when the feed was capped by the count parameter."New value: +"True when more stories remain beyond this page (hasMore). Absent on the last page of the feed."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "stories",
+      "feed",
+      "total",
+      "offset",
+      "hasMore"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `upstream_rejected`: The HN API answered with a 4xx status other than 429 — it rejected the request as built. `upstream_rate_limited`: The HN API answered with HTTP 429. `upstream_unavailable`: The HN API answered with a 5xx status. `upstream_html`: The HN API served an HTML error page with a 200 status, which it does under rate limiting or maintenance. `upstream_malformed`: The HN API answered with a 200 status and a body that is not JSON. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "upstream_rejected",
+            "upstream_rate_limited",
+            "upstream_unavailable",
+            "upstream_html",
+            "upstream_malformed"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "stories",
-  "feed",
-  "total",
-  "offset",
-  "hasMore"
-]

Changed3 schema fields changedJul 28, 2026
- changedInput schema / properties / count / type
```
Previous value: -"number"New value: +"integer"
```
- addedInput schema / properties / offset / maximum
```
Added value: +9007199254740991
```
- changedInput schema / properties / offset / type
```
Previous value: -"number"New value: +"integer"
```

Changed3 schema fields changedJun 12, 2026

addedOutput schema / properties / cap

Added value: +{
+  "description": "The count cap that was applied.",
+  "type": "number"
+}

addedOutput schema / properties / shown

Added value: +{
+  "description": "Number of stories returned on this page.",
+  "type": "number"
+}

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when the feed was capped by the count parameter.",
+  "type": "boolean"
+}

Changed2 schema fields changedMay 30, 2026

addedOutput schema / properties / notice

Added value: +{
+  "description": "Recovery hint when a page is empty — e.g. offset past end of feed or feed has no items. Absent on non-empty result pages.",
+  "type": "string"
+}

changedOutput schema / properties / offset / description

Previous value: -"Offset that was applied to this page (echoes input.offset)."New value: +"Offset that was applied to this page."

Changed1 schema field changedMay 11, 2026

addedOutput schema / properties / stories / items / properties / domain

Added value: +{
+  "description": "Bare hostname derived from url (e.g. \"github.com\", with leading \"www.\" stripped). Absent when url is missing or unparseable.",
+  "type": "string"
+}

Changed2 schema fields changedMay 6, 2026

changedInput schema / properties / count / description

Previous value: -"Number of stories to return. Each story is fetched individually — larger counts take longer."New value: +"Number of stories to return. Larger counts take longer."

changedOutput schema / properties / offset / description

Previous value: -"Offset used."New value: +"Offset that was applied to this page (echoes input.offset)."

Changed1 schema field changedApr 24, 2026
- addedOutput schema / properties / stories / items / description
```
Added value: +"A single story or job posting."
```

Changed5 schema fields changedApr 20, 2026

changedOutput schema / properties / stories / items / properties / by / description

Previous value: -"Author username."New value: +"Author username when provided by HN. Omitted when unknown."

changedOutput schema / properties / stories / items / properties / score / description

Previous value: -"Upvote count."New value: +"Upvote count when provided by HN. Omitted when unknown."

changedOutput schema / properties / stories / items / properties / time / description

Previous value: -"Unix timestamp."New value: +"Unix timestamp when provided by HN. Omitted when unknown."

changedOutput schema / properties / stories / items / properties / title / description

Previous value: -"Story title."New value: +"Story title when provided by HN. Omitted when unknown."

changedOutput schema / properties / stories / items / required

Previous value: -[
-  "id",
-  "title",
-  "score",
-  "by",
-  "time",
-  "type"
-]New value: +[
+  "id",
+  "type"
+]

First observedMar 28, 2026

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description does not contradict this. The description adds no new behavioral context beyond the annotation (e.g., rate limits, auth, or side effects). Given the annotation covers safety, the description's contribution is minimal, so a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action and lists key output fields. No wasted words; perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, an output schema (not shown) documents return values, and annotations cover safety, the description is adequate. It could mention pagination behavior, but the schema already documents offset and count for that. No critical missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% — all three parameters (feed, count, offset) are fully described in the schema. The tool description does not add any semantic detail beyond the schema, so it earns the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetch') and resource ('stories from an HN feed'), and lists the feed types and returned fields. It clearly distinguishes this from siblings like hn_get_thread or hn_get_user, which target different entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states the context (fetching feed stories) but does not explicitly mention alternatives or when not to use it. However, the tool's scope is self-evident given the named feed types and fields, providing clear context without exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All hn-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.