Onderwijsloket Assistent

Access to Onderwijsloket’s knowledge about working in education, with guided scheduling and feedback reporting through the Model Context Protocol (MCP).

Onderwijsloket Assistent lets AI assistants find guidance, compare education programs, explore institutions and regional advice services, and read stories and media from Onderwijsloket. It combines relevance-ranked search, structured collection records and complete Markdown resources in one discoverable interface.

What the server provides

• Ten core content collections with dedicated tools for browsing, searching and reading individual records.

• Education pathways through a source-defined questionnaire, matching routes and ordered step-by-step guidance.

• Geo-search for programs, educational institutions and regional education desks: resolve a city, postcode or address, search within a configurable radius and return nearest-first results with location and distance metadata.

• Filter discovery for education sectors, qualifications, audiences, career phases, roles, topics and tracks, with collection-specific search facets and counts.

• Structured detail records with relevant relationships, including program forms, institution locations, regional service areas, authors, sources and podcast participants.

• Readable resources for every core collection, with YAML metadata, Markdown content and transcripts where available.

• Source attribution through canonical website links and explicit indicators for missing content or bounded relationships.

• Self-describing contracts with collection descriptions, input/output schemas, supported filters, sorting and pagination.

Knowledge operations are read-only. Scheduling can create a telephone appointment after explicit user confirmation; feedback reporting can send a report to the team after explicit consent. MCP access requires no API key or sign-in. Source visibility is managed by Directus; the server validates and presents the data it receives.

Related MCP server: MCP Learning Server (mcp-intro)

Connect

Add the deployment’s /mcp URL to an MCP-compatible client. For a local instance:

http://localhost:3000/mcp

The client can discover tools, browse resource catalogues and read resources by URI. Start with list_collections to inspect the available content, then use describe_collection for a collection’s detailed contract.

Collections and tools

Each collection has a dedicated list, get and search tool. Record tools select their collection through the tool name; they do not take a collection argument.

Four shared tools complete the interface:

Source lists and search have separate filter contracts. Use get_filters for list operations and get_facets for search operations that support facets. Sector search accepts a query without facets. Paginated record results start at page 1 and allow up to 25 records per page.

Find and read content

For example, call search_articles to find guidance about an alternative route into teaching:

{
  "query": "zij-instroom",
  "page_size": 5
}

Search results contain lightweight records and matched snippets. Pass a returned ID to get_article for the full record, or follow its resource link for a Markdown document. The same search-to-detail workflow applies to the other collections.

Find nearby programs, institutions or advice services

Call search_programs, search_educational_institutions or search_regional_education_desks with location to search geographically. For example, search programs near Utrecht:

{
  "location": "Utrecht",
  "radius": 25000,
  "query": "leraar"
}

radius is optional and defaults to 50,000 metres. Keep query for the subject or program name; use location for the geographic centre. Results sort nearest first and include geo metadata with the matched coordinates, full address, applied radius and each hit's distance in metres. Regional desk distances approximate service-area coverage using indexed grid points. See geographic search for the contract and geocoding for Mapbox environment configuration.

Scheduling

When personal consultation is explicitly requested or a complex question remains unresolved, get_scheduling_link, get_scheduling_slots and book_appointment provide a guided Dutch/English telephone-booking flow. The server validates fresh form requirements and availability, supplies MCP client attribution and limits event creation to three attempts per hour per IP. No UI is included. Dutch and English form choices are configured; provider option validation and checkbox serialization still need a manual API check. See scheduling.

Feedback

submit_feedback sends reports about incorrect information, bugs or other issues to the team of Stichting Onderwijs in. The report-feedback prompt guides issue collection, review and explicit consent before submission. The chat dashboard's bug-icon action starts this workflow for a selected answer; clicking it does not submit a report.

Education pathways

Route data is exposed through a guided workflow rather than generic collection tools.

Pass the returned question-ID to answer-ID selections map between calls. Earlier answers can be changed; invalid downstream selections are cleared. Route matches provide guidance rather than admission or qualification guarantees. See education pathways for the contracts and differences from the website.

Prompts

In clients that support MCP prompts, select a workflow to guide the assistant through relevant tools and resources.

See MCP prompts for arguments and workflow details.

Resources and data quality

Every collection exposes a resource catalogue and a URI template:

onderwijsloket://{collection}/{id}

Here, collection is a registered name such as articles, programs or podcast_episodes. Browse resources/list for concrete record URIs or use the collection’s advertised template. MCP URIs identify resources inside the client; use source_url to open or cite the original website page when available.

Resources include YAML front matter and a Markdown body. Records retain their native fields: FAQs have answers, programs describe forms, and media can include transcripts. When text is absent, the resource explains this with a notice; structured fields preserve the source’s null value. Check content_warnings, relations_truncated and truncated where present before treating content as complete.

Individual record reads share a configurable cache between tools and resources, with a five-minute default per collection. Catalogues and selected discovery data are also cached. Ordinary lists and search results remain uncached. See resources, collection data and caching for the full behavior.

Run the server

Use Node.js 24, as specified in .nvmrc, and the Corepack-managed package manager pinned in package.json. Configure the Varlock environment profiles in envs/ with access to the required services and secrets provider.

pnpm install
pnpm dev

For a Node server build:

pnpm build
pnpm start

Module initialization and schema generation can require service credentials and network access during installation and builds. See development for environment setup and build requirements.

Release and deployment

Run Release and Deploy manually in GitHub Actions to release from main, deploy to Coolify, or do both. Combined runs deploy the exact release commit. Workflow success confirms that Coolify queued the deployment; verify completion in Coolify. See release and deployment for setup and operation.

Verification

The automated suite covers collection contracts, validation, search mappings, content rendering, cache behavior and the public MCP endpoint. HTTP integration tests build and run the application against local Directus and Algolia fixtures.

pnpm fmt:check
pnpm lint
pnpm typecheck
pnpm test

See the testing guide for focused commands, fixture conventions and verification boundaries.

Documentation

Maintained by Stichting Onderwijs in for Onderwijsloket. Report bugs and request features through GitHub issues.