headlesson

Connecting and using the tools

The MCP endpoint is https://mcp.headlesson.com/mcp. It uses JSON responses over Streamable HTTP and does not provide SSE or subscriptions. The new stateless MCP and the compatibility path for the older initialization procedure are handled separately. Registration and a conversation test in native Claude have not been done yet.

Local development endpoint: http://127.0.0.1:8787/mcp

Find and compare

headlesson_search example: {"query":"scheduling posts","axes":["auth","pricing","remote_mcp"]}

where is AND across axes and OR within an array of values. unknown does not match a confirmed condition. The known aliases licence / local_mcp_server / remote_mcp_server are normalized. Sort with {"axis":"last_release","order":"desc"}. unknown comes last. A request without a substantive query / ids / where returns an error with usage guidance.

curated means records with sources; registry means only a listing in the official Registry, which is unverified. Only when there are no curated candidates, or when include:["registry"] is given explicitly, the official Registry is queried with either the single longest ASCII word left after removing common words (ties broken in dictionary order) or a specified public namespace name (up to 200 characters). The full query is not sent; only the one extracted word is sent. Searches with known patterns such as URLs, email addresses, phone numbers or credentials, and searches with only IDs, only common words or only where, are not forwarded. Do not put secrets or personal information in public names either.

Registry results show the official registry_name and the declared remote URL and package type and identifier. These are listing information, not evidence that connecting or installing succeeds. The Registry searches partial matches of names and does not search the full text of descriptions or uses. At most 5 Registry candidates are returned, with where and sort applied within one page. curated results come first and the overall limit is kept. unknown stays unconfirmed. In registry_search, status and complete distinguish not queried, failure and an incomplete page. not_found means 0 candidates were returned; when the search is incomplete it does not mean the item does not exist upstream. curated_not_found is recorded as a signal that no researched record matched; include itself is not stored.

Get

headlesson_get example: {"id":"app:postiz","sections":["lesson","gotchas","axes"]}

When sections is omitted, it returns the description, entry points and the 6 main axes. Specifying axes returns all 17 axes, relations returns relations, and changes returns changes. The ID axes is the list of axis definitions, search-guide is the search rules, and feature:since-2025 is the first feature. If test.status is untested, the test has not been run. passed/partial/failed include the check date, version, environment, number of stages passed and execution evidence, and partial/failed also record the reason it stopped.

A live Registry ID is an identifier from which the official name can be recovered. get queries the official detail API again by that name and does not guarantee the snapshot from the time of the original search. Hash IDs from the old local full import cannot be resolved in the public runtime. Registry responses and mapping tables are not stored in the app, but records such as the query and returned IDs are kept as before. For details, see Privacy.

Changes and feedback

headlesson_whats_new example: {"since":"2025-01-01","about":"proto:mcp"}. Dates are the dates of the change. When omitted, the last 90 days are used.

headlesson_feedback example: {"text":"The lesson needs a clearer owner-login prerequisite.","kind":"comment","about":"app:postiz"}. The text is sent to the operator and stored. Do not include personal information, conversation text or secrets. Receipt does not mean it has been verified, adopted or published.

Contact

An LLM can contact the operator with the MCP tool headlesson_feedback. The official public channel for humans is Threads @head.lesson. For questions about using headlesson or to report a problem, email support@headlesson.com (forwarded to the operator's inbox; receipt from an outside address was confirmed on 2026-10-14). The privacy contact is given in the privacy policy.

Sources

Public URLs are kept. Sources that cannot be confirmed publicly are shown as operator-provided; not publicly verifiable, and editorial decisions as headlesson editorial judgement, keeping the check date, certainty, author and the position of the value. Operator observations (operator_own) and lesson.test do not inherit the default source.

Comparison axes

The main axes are auth / pricing / license / cli / local_mcp / remote_mcp. Also check the confirmation date and basis of each value.

Privacy · Markdown · 日本語