hn-mcp-server
Server Details
Browse Hacker News feeds, threads, and user profiles with full-text search.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/hn-mcp-server
- GitHub Stars
- 4
- Server Listing
- @cyanheads/hn-mcp-server
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.1/5 across 4 of 4 tools scored. Lowest: 3.5/5.
Each tool has a clearly distinct purpose: fetching story lists, retrieving threaded discussions, looking up user profiles, and searching content. There is no overlap in functionality.
All tool names follow a consistent 'hn_<verb>_<noun>' pattern (e.g., hn_get_stories, hn_search_content), making them predictable and easy to understand.
With 4 tools, the server covers the essential read-only operations for Hacker News. While more tools could be added (e.g., for voting or commenting), the count is reasonable for a focused server.
The tool set provides access to story feeds, individual threads, user profiles, and search. A minor gap is the lack of a direct 'get story by ID' tool, though this can be approximated via hn_get_thread with depth 0. Overall, core HN interaction is covered.
Available Tools
4 toolshn_get_storiesHn Get StoriesARead-onlyInspect
Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count for each story.
| Name | Required | Description | Default |
|---|---|---|---|
| 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
| Name | Required | Description |
|---|---|---|
| cap | No | The count cap that was applied. |
| feed | Yes | Which feed was fetched. |
| shown | No | Number of stories returned on this page. |
| total | Yes | Total items in the feed (up to 500 for top/new/best, 200 for ask/show/jobs). |
| notice | No | 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. |
| offset | Yes | Offset that was applied to this page. |
| hasMore | Yes | Whether more stories are available beyond this page. |
| stories | Yes | Stories from the feed, ordered by HN ranking. |
| truncated | No | True when the feed was capped by the count parameter. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, and the description adds context about the returned fields (title, URL, score, author, comment count). No contradictions. Additional behavioral details like rate limits are not necessary given the low stakes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the core action and resource. Every word earns its place. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 parameters, output schema exists), the description is complete enough. It covers the tool's purpose and output, but could mention pagination behavior (offset/count) explicitly, though it's covered in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value beyond the schema by listing the fields returned (title, URL, score, author, comment count), which are not in the input schema. This helps the agent understand what data it will receive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 'HN feed', enumerates the feed types, and mentions key return fields. It clearly distinguishes from siblings like hn_get_thread and hn_get_user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching story lists from HN feeds, but does not explicitly state when to use this tool versus alternatives or provide when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hn_get_threadHn Get ThreadARead-onlyInspect
Get an item and its comment tree as a threaded discussion, with child comments resolved recursively. Use depth 0 for an item-only lookup.
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | How many levels of replies to resolve. 0 = just the item, no comments. 1 = direct replies only. Popular stories often have more top-level comments than maxComments — to see nesting, raise maxComments together with depth, or call again with a specific comment's itemId to drill into a subtree. | |
| itemId | Yes | ID of the story, comment, or poll to fetch the thread for. | |
| maxComments | No | Maximum total comments to include across all depth levels. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The maxComments cap that was applied. |
| item | Yes | The root item (story, comment, or poll). |
| shown | No | Number of comments returned. |
| notice | No | Truncation context: counts of deleted/dead comments dropped during traversal, or pagination hint when totalLoaded < totalAvailable. Absent when no comments were dropped and all available comments were loaded. |
| comments | Yes | Flat comment list ordered breadth-first by rank: highest-ranked top-level comments first, then their replies. Use depth/parentId to reconstruct nesting. |
| truncated | No | True when the comment list was capped by maxComments. |
| totalLoaded | Yes | Number of comments actually fetched and included. |
| totalAvailable | No | Total comment count from the root item. If totalLoaded < totalAvailable, raise maxComments (and depth, if you want nested replies) and call again. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description explains that child comments are resolved recursively and details how depth and maxComments interact, providing clear behavioral expectations without contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two front-loaded sentences that convey the core functionality and key usage guidance without extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and detailed schema descriptions, the description adequately covers the tool's purpose and usage. It could mention the return structure, but it's not necessary for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already has 100% description coverage with detailed parameter explanations. The description adds value by offering usage tips like using depth 0 for item-only lookup and explaining parameter interactions, justifying a score above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'an item and its comment tree', and the output format 'threaded discussion'. It also distinguishes from sibling tools like hn_get_stories and hn_get_user by focusing on threaded discussion of a single item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides specific guidance on using depth 0 for item-only lookup and explains the interplay between depth and maxComments. However, it does not explicitly state when to use this tool over siblings, though the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hn_get_userHn Get UserARead-onlyInspect
Get an HN user profile with karma, about, and optionally their most recent submissions resolved into full items.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | HN username. Case-sensitive. | |
| submissionCount | No | Number of recent submissions to resolve. Only used when includeSubmissions is true. | |
| includeSubmissions | No | Resolve the user's most recent submissions into full items. Without this, only the submission count is available. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The submissionCount cap that was applied. |
| user | Yes | User profile. |
| shown | No | Number of submissions returned. |
| notice | No | Pagination caveat when submissions were truncated. Absent when all submissions fit within the requested count or includeSubmissions is false. |
| truncated | No | True when submissions were capped by submissionCount. |
| submissions | No | Recent submissions, most recent first. Only present when includeSubmissions is true. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds behavioral context by specifying the returned fields (karma, about) and the optional resolution of submissions, without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and optional behavior with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers the core functionality and optional submissions, though it lacks explicit error handling or edge case details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by noting case-sensitivity for username and clarifying that submissionCount is only used when includeSubmissions is true.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'get' and resource 'user profile', and distinguishes from sibling tools like hn_get_stories, hn_get_thread, and hn_search_content by focusing on user-specific data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies usage for retrieving user profiles, it does not explicitly state when to use this tool versus alternatives or provide any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
hn_search_contentHn Search ContentARead-onlyInspect
Search Hacker News stories and comments via Algolia. Filterable by content type, author, date range, and minimum points.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination (0-indexed). | |
| sort | No | Sort order. "relevance" for best match, "date" for most recent first. | relevance |
| tags | No | Filter results by content type. Omit to search all types. | |
| count | No | Number of results to return. | |
| query | Yes | Search terms. Supports simple keywords — Algolia handles stemming and relevance. | |
| author | No | Filter results to a specific author. Useful for finding a user's posts on a topic (hn_get_user only shows recent submissions). | |
| dateRange | No | Filter to a date window. Useful for finding discussions about recent events. | |
| minPoints | No | Minimum score/points. Filters out low-engagement content. |
Output Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The count cap that was applied. |
| hits | Yes | Search results ranked by sort order. |
| page | Yes | Current page number (0-indexed). |
| query | Yes | The query that was searched. |
| shown | No | Number of hits returned. |
| notice | No | Recovery hint when results are empty — names the filters applied, for relaxing the search. Absent on non-empty result pages. |
| totalHits | Yes | Total matching results across all pages. |
| truncated | No | True when the hit list was capped by the count parameter. |
| totalPages | Yes | Total pages available. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'via Algolia' as a backend detail, but does not disclose behaviors beyond the readOnlyHint annotation. With annotations, the description offers minimal extra behavioral insight, but it does not contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, clear sentences with no unnecessary words. It efficiently conveys the core functionality and filtering capabilities.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers the main purpose and key filters, it omits mention of sorting, pagination (page, count), and the existence of a structured output schema. Given the tool's complexity (8 params, nested objects), additional summary of sorting and pagination would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters thoroughly. The description only summarizes filtering options (content type, author, date range, min points) without adding new semantics, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (search), the resource (Hacker News content via Algolia), and lists filtering options. It distinguishes from sibling tools by focusing on search rather than retrieval, but could explicitly exclude alternatives for higher precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives guidance is given, though the author parameter description mentions comparing with hn_get_user. The description implies a general search tool but lacks direct context for sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Your Connectors
Sign in to create a connector for this server.