Documentation available through Learnosity Build Aide MCP

The Learnosity Build Aide MCP server indexes Learnosity's published documentation and makes it searchable and retrievable by your assistant. Learnosity Build Aide MCP retrieves information from these sources to provide documentation-grounded guidance.

• Learnosity help site - API reference, integration guides, technical documentation, and how-to articles.
• Author guide - Authoring workflows, question types, and content creation in the Author Site.
• Feedback Aide documentation - Feedback Aide API reference, including endpoints and request and response formats.
• Learnosity demos - Learnosity API and partner demos.
• Learnosity on GitHub - Learnosity's public repositories, including SDKs, demos, and reference implementations.

Because the assistant retrieves from these sources directly, it can cite where an answer came from, and will tell you when documentation does not cover a topic rather than filling the gap with a guess.

Tools

The server exposes eight read-only tools in three groups:

• Documentation tools for discovering, searching, and retrieving Learnosity documentation.
• Skills tools for discovering and retrieving Learnosity skills.
• Feedback tools for sharing feedback on Learnosity Build Aide MCP.

Some documentation tools accept a source identifier to specify which documentation sources to use. The available source identifiers are:

• Learnosity help site: help_site
• Author guide: author_guide
• Feedback Aide: feedback_aide
• Learnosity demos: demos
• Learnosity on GitHub: github

Documentation tools

list_docs_sources

Lists the configured documentation sources. Use this tool to identify the available sources and their source identifiers.

This tool does not require any parameters. It returns the source identifier, type, and title for each configured source.

list_docs_categories

Lists the available documentation categories.

The response includes the source, category identifier, and category name. Results are sorted by source and then by category name.

Categories are available for the Learnosity help site and author guide. Feedback Aide, Learnosity demos, and GitHub do not use categories.

search_docs_sources

Searches the indexed Learnosity documentation. Use this as the primary tool for discovering relevant documentation.

The response includes the query, applied category filter, and matching results. Each result can include the source, article identifier, resource URI, title, URL, section and category information, a content snippet, match type, and images.

The response also includes an alerts array, but only when the golden path gate is triggered by the query or by one of the results. It is absent from every other response. See What the golden path gate does.

An invalid source identifier returns an error.

read_document

Retrieves an indexed document.

The response includes the source, article identifier, title, URL, section and category information, last-updated date, markdown content, and images.

Images are returned separately from the markdown content in an images array.

Skills tools

skills_list

Lists the available Learnosity skills.

When you specify apis, the response includes only skills that declare every specified API. API matching is case-insensitive.

Each result includes the skill identifier, resource URI, size, title, goal, and APIs covered by the skill.

skills_read

Retrieves a skill and returns its content in markdown format.

If the skill exceeds max_bytes, its content is truncated at a character boundary and the response indicates that the content has been truncated.

skills_search

Searches skills by identifier, title, goal, declared APIs, or content.

The response includes matching skills, the field containing the match, and a content snippet.

Feedback tools

get_feedback_link

Retrieves the URL of the Learnosity Build Aide MCP feedback page, where you can submit feedback about Learnosity Build Aide MCP.

This tool does not require any parameters. It returns a message for your AI coding assistant to display and the feedback page URL.

The tool does not collect or submit feedback. Your AI coding assistant provides the link, which you can use to access the feedback page and submit your feedback.

Resources

Alongside tools, the server publishes MCP resources under the learnosity:// scheme. Resources suit clients that prefer addressable reads to tool calls, and they return the same content.

Note that resource URIs use hyphens where source identifiers use underscores - the help site is help_site as a tool argument and help-site in a resource URI. Every search result includes its own resource URI, so you rarely need to construct one by hand.

Transport and sessions management

Learnosity Build Aide MCP uses the MCP Streamable HTTP transport. Clients send JSON-RPC requests in the body of a HTTP POST request. The server returns responses as an HTTP event stream, allowing progress notifications to be sent before the final result.

The Accept header must include both application/json and text/event-stream. Requests that specify only one of these content types receive a HTTP 406 Not Acceptable response.

Clients that establish a connection using an initialization handshake receive a Mcp-Session-Id header in the initial response. Include this session identifier in all subsequent requests, including the GET request that opens the server-to-client event stream and the DELETE request that terminates the session.

Clients using MCP protocol version 2026-07-28 or later send self-contained requests and do not receive a session identifier.

To check service availability, send a GET request to /health-check. The endpoint returns 200 while the service is still serving, so read the response body rather than the status code.

Errors

The documentation and Skills tools can return the following errors:

• "Unknown source: {source}" - The specified source value does not match a configured source identifier.
• "Unknown source(s): {sources}" - One or more values in sources do not match configured source identifiers.
• "Article {article_id} not found in local cache. Documentation is always up to date." - The specified article_id is not available in the documentation index.
• "Invalid skill id. Must be kebab-case ([a-z0-9-])." - The specified skill_id does not use kebab case.
• "Skill '{skill_id}' not found" - The specified skill_id does not match an available Skill.
• "Skill '{skill_id}' could not be parsed." - The requested Skill could not be read.

Search and the golden path gate

How search works

Learnosity Build Aide MCP combines lexical and semantic search to find relevant information in the indexed documentation. Results from both search methods are merged and ranked, and each result identifies the type of match.

Title matches are ranked higher than body-content matches. Release log articles are given a lower priority so that documentation explaining a feature is prioritized over release notes that only mention it.

If semantic search is unavailable, Learnosity Build Aide MCP returns lexical search results instead.

The golden path

The golden path represents the recommended APIs for a typical Learnosity integration:

Author API → Items API → Reports API

Author API is used to create assessment content and Activities. Items API delivers the Activity and creates a learner session. Reports API uses the Activity and session information to report on the results. The golden path skill provides guidance for this end-to-end workflow.

Learnosity also publishes lower-level APIs for custom builds. They are fully supported and documented, but the recommended API is generally a better starting point for common integration workflows.

What the golden path gate does

When search_docs_sources identifies a search for Questions API, Assess API, or Question Editor API, it can return a golden path alert recommending the corresponding higher-level API.

The golden path gate can produce the following outcomes:

• Advisory - The query references a lower-level API, but no search result matches that API. No results are withheld, and the response includes a recommendation to use the golden path.
• Gating - One or more results match a lower-level API. Matching results are withheld, while other results are returned. The response indicates how many results were withheld.
• Reason provided - An off_golden_path_reason is supplied with the request. Matching results are returned without being withheld.

Using off_golden_path_reason

Use off_golden_path_reason to explain why your integration needs a lower-level API instead of the recommended API. Specify the parameter on each applicable search request because the value does not persist between searches.

search_docs_sources(
  query = "Assess API initialisation options",
  off_golden_path_reason = "Existing player built on Assess API; migrating is out of scope this quarter"
)

If the reason does not identify a specific requirement for using the lower-level API, Learnosity Build Aide MCP can continue to recommend the golden path.

The golden path gate applies only to discovery through search_docs_sources. It does not prevent direct access to documentation, Skills, or MCP resources.

Skills

Skills are the most substantial part of the server. Skills provide guided workflows for specific Learnosity integration tasks. A skill can provide the steps, decisions, supporting documentation, and guidance needed to complete a workflow.

Skills are composable - a skill can reference another skill. This means you get consistent, non-contradictory advice regardless of which entry point you start from.

Available skills catalog

The catalog is continuously expanding. Skills currently available:

Ask your assistant to list the currently available skills for an authoritative, up-to-date answer.

Example: Upgrade to a newer Learnosity LTS version

This illustrates the intended workflow. Exact assistant behavior varies by client and model.

1. Establish the upgrade path

"Use the Learnosity Build Aide MCP LTS Upgrade Paths skill to plan an upgrade from the LTS version we're pinned to up to the current release. We're five versions behind."

The assistant retrieves the LTS Upgrade Paths skill and returns the upgrade methodology, the releases between your current and target version, and the breaking changes introduced at each one. A multi-version jump is returned as a sequence rather than a single hop, so you can see which release introduced each change.

2. Narrow the breaking changes to your integration

"Which of those breaking changes affect Items API and Reports API? We don't use Author API."

The assistant filters the upgrade guidance to the APIs and features your integration actually uses, and cites the documentation behind each change so you can confirm the detail rather than taking it on trust.

If the upgrade also means moving to a newer SDK, ask for that skill directly:

"Now use the SDK Install / set-up skill to show me how to move our Node.js SDK to the version that supports the target LTS."

3. Verify your configuration against the target version

"Check my Items API initialization options against the target LTS and flag anything removed or renamed."

The assistant validates your initialization object against the published reference for the target version and flags options that have been removed, renamed, or given new defaults.