@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-mcp

Or run it without installing, which is what most MCP clients do:

npx @stonedogcode/howto-mcp

Related 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.

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.

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.

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

Apache-2.0. See LICENSE and NOTICE.