howto-mcp
This server provides a read-only interface to a how-to documentation portal, secured by bearer-token authentication and strict permission enforcement. Capabilities include:
Search articles: Full-text search with relevance ranking across all accessible repositories; supports optional repository filtering and a limit (1–50, default 10).
Read an article: Retrieve the full content of a specific article by repository and slug.
List repositories: View accessible repositories along with their article counts.
All operations respect user permissions; inaccessible content is hidden and errors deliberately mimic non-existence to avoid information leakage.
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., "@howto-mcp What articles are there about rate limiting?"
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.
@stonedogcode/howto-mcp
A Model Context Protocol server for a how-to documentation portal. Ask what has been written, and read it, without leaving your editor.
> What articles exist about authentication?
3 articles match "authentication".
## Signing in with a passkey
repository: Alpha · slug: signing-in-with-a-passkey
written for: Support (as labelled by its source)
matched headings: Registering a device
…It contains no documentation of its own, and no permission model. It asks a portal, and the portal answers as the user whose token it holds.
Install
npm install -g @stonedogcode/howto-mcpOr run it without installing, which is what most MCP clients do:
npx @stonedogcode/howto-mcpRelated MCP server: MCP Documentation Server
Before you configure it
The portal has to be running and reachable from this machine. This server is a client and holds nothing of its own, so a portal that is down looks exactly like a server that is broken.
Check it first, so a later failure has one fewer possible cause:
curl -s https://howto.example.com/api/health
# {"status":"ok", … ,"database":"ok"}status: degraded means the portal is up but its database is not. Fix that
before going further — search will fail and the error will point here.
And you need a token. Your portal issues them; how depends on the portal. Whatever the mechanism, the token is shown once and stored hashed, so keep it when it is printed. See "The token is an identity, not a key" below before choosing whose it is.
Configure
Two environment variables, both required. The server refuses to start without them rather than failing every request afterwards — a server that starts and then refuses everything looks like a broken portal.
| Base URL of your portal, e.g. |
| A token issued by that portal |
Claude Code
claude mcp add howto --scope user \
--env HOWTO_PORTAL_URL=https://howto.example.com \
--env HOWTO_API_TOKEN=… \
-- npx -y @stonedogcode/howto-mcp--scope user registers it for every project rather than the directory you
happen to be in. Documentation is not project-specific, and a server registered
in one checkout is invisible from the next one — which reads as the server
having stopped working.
Then confirm it, rather than assuming:
claude mcp list
# howto: npx -y @stonedogcode/howto-mcp - ✔ Connected✔ Connected means the server started and answered. It does not mean the
token is good — that is not checked until the first search, by design, because
the portal is the thing that decides.
Restart Claude Code before expecting the tools in a session that was already open. Then ask it something:
What articles exist about authentication?
Any client that takes a JSON config
{
"mcpServers": {
"howto": {
"command": "npx",
"args": ["-y", "@stonedogcode/howto-mcp"],
"env": {
"HOWTO_PORTAL_URL": "https://howto.example.com",
"HOWTO_API_TOKEN": "…"
}
}
}
}When it does not work
The failures are deliberately hard to tell apart from the outside — that is the access model working, not a bad error message — so here is what each one means.
What you see | What it is |
| The variable did not reach the process. Client configs vary in whether they inherit your shell; set it in the config, not your profile. |
| Wrong URL, portal down, or a network path that does not exist from here. Try the |
| The token is wrong, revoked, or belongs to a deleted user. Issue a new one; the old value cannot be recovered. |
| The search ran and its user may read nothing that matches. This is also what you get when the token's user has no grants at all — see below. |
| The token is valid and its user has been granted nothing. Someone with admin rights on the portal grants repositories. |
The last two are worth reading twice: a working setup with no access looks
almost exactly like a working setup with nothing to find. If list_repos is
empty, the problem is grants, not configuration.
The token is an identity, not a key
This server reads exactly what its token's user reads — no more. It performs no access check of its own, deliberately: a second permission model beside the portal's would be a second answer to the same question, and the two drift. A client-side check that says yes when the server would say no is how a tool ends up showing somebody something.
So the way to scope this server is to choose whose token it is. Issue it to a user with the narrowest access that still makes the archive useful to you, and revoke it when that person's access changes.
The token is long-lived and sits in a config file on disk. Treat it as you would any credential in one.
Tools
search_articles
Search across every repository the token may read. Ranked by relevance — titles outrank summaries, which outrank headings, which outrank prose — and every word in the query must appear, so adding a word narrows the results.
Argument | ||
| required | What to look for |
| optional | Default 10, maximum 50 |
| optional | Restrict to one repository by name |
get_article
Read one article in full, by the repository and slug that search returned.
list_repos
The repositories this token may read, and how many articles each holds.
What it will not tell you
Three things, on purpose, because a documentation tool that is careless here is worse than none:
It never reports what it could not see. No "3 of 40 match" — that would disclose that 37 exist. The portal declines to mention them; repeating a total would undo that.
A missing article and a forbidden one give the same answer. Two different answers let a caller map what exists by guessing.
Errors carry no internals. Not the URL, not the token, not the portal's own error text, not a stack. Error messages are where internal detail escapes most easily, because whoever writes one is debugging at the time.
Each of those has a test asserting it, including one that fails if an error message ever repeats the token or the host.
Requirements
Node 20 or newer, and a portal exposing /api/search, /api/articles/… and
/api/repos with bearer-token authentication.
Licence
Available Tools
3 toolsget_articleRead a how-to articleA
Read one article in full, by the repository and slug that search_articles returned. Refuses identically whether the article does not exist or the token's user may not read it.
Inputs: repo (required), slug (required).
list_reposList readable repositoriesA
The repositories this token may read, with how many articles each holds. Says nothing about repositories it may not read.
Inputs: no named parameters.
search_articlesSearch how-to articlesA
Search the how-to documentation across every repository this token may read. Ranked by relevance: titles outrank summaries, which outrank headings, which outrank prose. Every word in the query must appear, so adding a word narrows the results. Returns only articles the token's user is entitled to read.
Inputs: query (required), repo, limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool performs a clearly distinct function: searching articles, retrieving a specific article, and listing accessible repositories. No overlap or ambiguity.
All tool names follow the verb_noun pattern: search_articles, get_article, list_repos. Consistent and predictable.
Three tools is a well-scoped, focused set for a read-only documentation server. Each tool is necessary and earns its place.
The core workflows of discovering and reading articles are covered. A potential minor gap is the inability to browse all articles in a repo without a search query, but search can handle most use cases.
Maintenance
Related MCP Connectors
MCP server for querying Forkast documentation
Read-only MCP server for the OrchestKit docs: full-text search + Markdown fetch. No auth.
Help center for SaaS teams. 14-tool MCP server for articles, collections, and search.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Related MCP Servers
- AlicenseAqualityBmaintenanceA Model Context Protocol (MCP) server that scrapes, indexes, and searches documentation for third-party software libraries and packages, supporting versioning and hybrid search.124,092 npm1,904MIT
- AlicenseNot gradedqualityDmaintenanceA server that provides organized documentation content for various applications using the Model Context Protocol, enabling AI assistants to access quickstart guides and code examples.MIT
- AlicenseCqualityDmaintenanceA Model Context Protocol server that enables intelligent searching across documentation for 30+ programming libraries and frameworks, fetching relevant information from official sources.238MIT
- AlicenseNot gradedqualityAmaintenanceSelf-hosted MCP server that indexes documentation from various sources and makes it searchable by AI assistants via the Model Context Protocol and REST API.91Apache 2.0