Provides tools to read published Hoppscotch API documentation, allowing users to search for endpoints, list endpoints, and retrieve detailed endpoint information and saved response examples.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Hoppscotch Public Docs MCP Search documentation at https://api-docs.hoppscotch.io/view/abc123 for login endpoint details"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A read-only MCP server for published Hoppscotch API documentation. Search requests, inspect endpoint details, and read saved response examples. It uses Hoppscotch's public documentation endpoint; no Hoppscotch account or token is required.
Copy one of these prompts and paste it into your MCP-capable AI agent.
Install the Hoppscotch Public Docs MCP server for this AI client from https://github.com/KidiXDev/hoppscotch-public-docs-mcp.
Follow the repository README and install it using uv. Install uv first if needed.
Configure this client to run:
hoppscotch-public-docs-mcp
Do not set a default Hoppscotch document URL. I will give you a published URL for each project; pass it as doc_url on every tool call.
Verify that the server exposes get_document, search_documentation, list_endpoints, and get_endpoint.
Tell me what you configured and whether I need to restart the client.Install the Hoppscotch Public Docs MCP server for this AI client from https://github.com/KidiXDev/hoppscotch-public-docs-mcp.
Use the prebuilt Docker image:
ghcr.io/kidixdev/hoppscotch-public-docs-mcp:latest
Configure this client to run the MCP server over stdio using:
docker run --rm -i ghcr.io/kidixdev/hoppscotch-public-docs-mcp:latest
Do not set a default Hoppscotch document URL. I will give you a published URL for each project; pass it as doc_url on every tool call.
Verify that the server exposes get_document, search_documentation, list_endpoints, and get_endpoint.
Tell me what you configured and whether I need to restart the client.Requires Python 3.10+ and uv.
Install directly from GitHub:
uv tool install git+https://github.com/KidiXDev/hoppscotch-public-docs-mcp.gitOr install from a checkout:
uv tool install .Then configure your MCP client.
To check a published document:
hoppscotch-public-docs-mcp --check https://api-docs.hoppscotch.io/view/YOUR_DOC_IDIf the command is not found after installation, run uv tool update-shell, reopen your terminal, or use the executable's absolute path in your MCP client.
Pull the prebuilt image:
docker pull ghcr.io/kidixdev/hoppscotch-public-docs-mcp:latestCheck a published document:
docker run --rm \
ghcr.io/kidixdev/hoppscotch-public-docs-mcp:latest \
--check https://api-docs.hoppscotch.io/view/YOUR_DOC_IDFor an MCP client's stdio configuration, use:
docker run --rm -i ghcr.io/kidixdev/hoppscotch-public-docs-mcp:latestKeep -i and do not detach the container.
Related MCP server: Documentation Fetcher & RAG Search
Start the server without a document URL. Pass the project's published /view/<slug> URL as doc_url on each tool call, optionally ending in a version.
For example:
search_documentation(
query="tenant",
doc_url="https://api-docs.hoppscotch.io/view/YOUR_DOC_ID"
)Include the relevant URL in your request to the agent so it can pass the right URL for each project.
Without a document URL, a tool call returns an error.
For compatible self-hosted deployments, these optional settings change where the server reads published docs:
Variable | Purpose | Default |
| Allowed public viewer origin |
|
| Backend base URL for compatible self-hosted deployments |
|
For a self-hosted deployment using the same /v1/published-docs route, set both values to that deployment's viewer origin and backend /v1 URL.
Per-call doc_url values must match the configured viewer origin.
Tool | What it returns |
| Title, version, folder names, environment variable names, and endpoint count |
| Ranked, short endpoint summaries for API concepts in a task; up to 50 per page |
| Exact text matches by folder, name, method, URL, or description; up to 100 per page |
| Request details and available response names; the named saved response when requested |
These configurations start a stdio server without selecting a project.
Give your agent the published URL for the project you are working on; it passes that URL as doc_url when calling tools.
The server normally prints nothing in a terminal because it exchanges protocol messages over stdin/stdout.
The examples below use the uv installation.
If you use Docker, replace the executable with:
{
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"ghcr.io/kidixdev/hoppscotch-public-docs-mcp:latest"
]
}Add this to ~/.codex/config.toml or a project .codex/config.toml:
[mcp_servers.hoppscotch_docs]
command = "hoppscotch-public-docs-mcp"Run:
codex mcp listSee the Codex MCP guide.
claude mcp add --scope user --transport stdio hoppscotch-docs -- hoppscotch-public-docs-mcp
claude mcp get hoppscotch-docsSee the Claude Code MCP guide.
For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows, then fully restart the app:
{
"mcpServers": {
"hoppscotch-docs": {
"command": "hoppscotch-public-docs-mcp"
}
}
}Use the command's absolute path if Claude Desktop cannot find it.
See the MCP Python SDK host guide.
In the IDE, open:
MCP Servers → Manage MCP Servers → View raw configIn Antigravity CLI, edit ~/.gemini/config/mcp_config.json or .agents/mcp_config.json in a workspace:
{
"mcpServers": {
"hoppscotch-docs": {
"command": "hoppscotch-public-docs-mcp"
}
}
}See the Antigravity MCP guide.
For Copilot in VS Code, create .vscode/mcp.json in your project or use MCP: Open User Configuration:
{
"servers": {
"hoppscotch-docs": {
"type": "stdio",
"command": "hoppscotch-public-docs-mcp"
}
}
}Use Copilot Chat Agent mode and enable the server in its tools picker.
For Copilot CLI:
copilot mcp add hoppscotch-docs -- hoppscotch-public-docs-mcp
copilot mcp get hoppscotch-docsThe CLI also accepts a portable ~/.copilot/mcp-config.json with a top-level mcpServers object. VS Code's .vscode/mcp.json uses servers.
See VS Code's MCP configuration reference and the Copilot CLI MCP guide.
To run an HTTP server locally with Docker:
docker run --rm \
-p 127.0.0.1:8000:8000 \
ghcr.io/kidixdev/hoppscotch-public-docs-mcp:latest \
--http \
--host 0.0.0.0Connect a Streamable HTTP MCP client to:
http://127.0.0.1:8000/mcpPass doc_url to each tool call.
For a local Python process:
hoppscotch-public-docs-mcp --httpuv run python -m unittest -v
uv run hoppscotch-public-docs-mcp --check https://api-docs.hoppscotch.io/view/YOUR_DOC_IDBuild the Docker image locally:
docker build -t hoppscotch-public-docs-mcp .This project is licensed under MIT.
Get a published document's title, versions, folders, variables, and endpoint count.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The word 'Get' and the 'published document' qualifier imply a read-only operation on already-published docs, which is useful context, but there is no disclosure of permission requirements, behavior for unpublished/nonexistent URLs, or error handling.
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?
A single front-loaded sentence that lists the payload contents efficiently with no filler. It is appropriately sized for a simple lookup tool.
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?
The description usefully enumerates the return contents in the absence of an output schema, which partially compensates. However, with no annotations and an entirely undocumented input parameter, an agent still lacks enough to call it confidently with correct argument semantics.
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 description coverage is 0% and the single parameter doc_url has no schema description; the description does not explain the expected URL format, whether it can be a slug or full URL, or that it defaults to empty. The parameter is effectively undocumented in both places.
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?
States a specific verb (Get) and resource (document) and enumerates the returned fields (title, versions, folders, variables, endpoint count), which makes the tool's scope concrete. It does not explicitly differentiate itself from siblings like get_endpoint or search_documentation, though the noun 'document' vs 'endpoint' provides implicit separation.
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?
There is no guidance on when to use this tool versus list_endpoints, search_documentation, or get_endpoint, and no mention of prerequisites. The agent must infer that this is the per-document detail lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full request details for an ID from search_documentation or list_endpoints. Pass response_name for a saved response example. Call only for relevant routes to keep context small.
| Name | Required | Description | Default |
|---|---|---|---|
| doc_url | No | ||
| request_id | Yes | ||
| response_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses a context-economy constraint ('keep context small'), implying large return payloads, but says nothing about what a call consumes, whether results are cached, or how large responses behave.
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?
Three short sentences, front-loaded with the core action and with zero filler. The final advisory sentence earns its place by constraining call frequency.
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?
With no annotations and no output schema, the description should say more about the shape and volume of what comes back, since it already raises the context-size concern. The workflow guidance is good, but the return-value picture remains incomplete.
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 description coverage is 0% across 3 params, so the description must compensate. It explains request_id's provenance and response_name's purpose, but doc_url is entirely undefined and request_id's format (ID vs URL) is left ambiguous.
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?
States a specific verb and resource: 'Get full request details for an ID'. It also names the sibling tools that produce the ID, which lets an agent place it in the workflow. It does not specify what 'full request details' includes (headers, body, params), so it stops short of a 5.
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?
Gives explicit sourcing guidance ('ID from search_documentation or list_endpoints'), a conditional for response_name, and a caution to call it only for relevant routes. It does not contrast against get_document, so the sibling boundary is only partly drawn.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List endpoints using an exact text fragment, or list all with query="". Paginate for all results.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| offset | No | ||
| doc_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose that results are paginated and that pagination is required to see everything, but says nothing about authentication needs, whether results are ordered, or what a page contains (no output schema either).
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?
Two short sentences, front-loaded with the core action and the query-mode distinction; no filler. Every clause carries 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?
For a 4-parameter tool with no annotations and no output schema, the description covers only query semantics and pagination. The doc_url scoping parameter, limit default, and offset behavior are unexplained, leaving real gaps an agent would guess at.
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 0%, so the description must compensate. It does explain the query parameter's semantics (exact text fragment; empty string means list all), but limit, offset, and especially the cryptic doc_url are left entirely undocumented in both schema and description.
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?
States a specific verb (List) and resource (endpoints) and clarifies the two modes: filtered by exact text fragment or unfiltered via query="". It does not explicitly name a sibling like get_endpoint to contrast with, so it falls short of a 5.
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?
It implies when to use each mode (fragment search vs empty query for all), which is useful context, but gives no explicit exclusions and never mentions the sibling tools (get_endpoint, search_documentation) that an agent must choose between.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start here for broad tasks: rank endpoints by API concepts in a phrase. Returns short summaries and IDs, not full docs. Search focused concepts (e.g. tenant), paginate when the user asks for all, then use get_endpoint for needed routes. This reads documentation, not live API data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| offset | No | ||
| doc_url | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does well: it discloses that results are summaries/IDs not full docs, that pagination is available, and crucially that it "reads documentation, not live API data" (read-only, static source). It omits any auth, rate-limit, or result-size behavior.
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?
Four short sentences, front-loaded with the entry condition and scope, then result shape, then usage steps. Every sentence carries distinct information with no repetition.
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?
Covers the essentials for a search tool with no annotations and no output schema: source (docs, not live data), result shape, and next step. The unexplained doc_url parameter and the untouched get_document/list_endpoints siblings are the remaining gap.
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 description coverage is 0%, so all four parameters (query, limit, offset, doc_url) are undocumented by structured data. The phrase "paginate when the user asks for all" implies limit/offset exist and when to use them, but doc_url is never explained and no syntax or format is given for query.
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?
States a specific verb and resource: it ranks endpoints by API concepts matched from a phrase, and explicitly scopes the return to short summaries and IDs rather than full docs. It is clearly distinguishable from get_endpoint, which it names as the follow-up for actual routes.
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?
"Start here for broad tasks" gives a clear entry condition, and "then use get_endpoint for needed routes" names the follow-up tool. "paginate when the user asks for all" gives a concrete usage rule. It never contrasts with get_document or list_endpoints, so sibling routing is incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_documentget_endpointlist_endpointssearch_documentationScored across 4 tools
The tools mostly target distinct actions: get_document retrieves metadata, search_documentation discovers endpoints by concepts, list_endpoints filters by exact text, and get_endpoint fetches full details. list_endpoints and search_documentation both return endpoint lists, but descriptions give clear guidance on when to use each, so ambiguity is minor.
All tool names follow a consistent verb_noun snake_case pattern: get_document, list_endpoints, search_documentation, get_endpoint. The singular/plural variation reflects whether one or many resources are returned, which is predictable.
Four tools are well-scoped for a read-only public documentation MCP. Each tool has a clear purpose and there is no redundant or trivial tool, making the set appropriately sized.
The surface covers document metadata, endpoint listing, concept search, and full endpoint detail retrieval, which are the core read-only operations. Minor gaps exist, such as no dedicated tool for listing saved response examples or separately browsing folders, but these are largely addressable through existing tools.
Read-only HotAPI documentation: search integration guides and inspect OpenAPI operations.
Version-true web3 docs, ABIs and human-validated integration recipes over MCP.
Search your Glasp web and Kindle highlights, notes, and AI memories from any MCP client. Read-only.
Search and read the aicoolies catalog of AI and developer tools via a remote MCP knowledge graph.
