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., "@szkoly-mcp Jakie podstawówki są najbliżej ul. Garbary 10 w Poznaniu?"
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.
Adres MCP: https://szkoly.compabase.com/mcp (Streamable HTTP, bez logowania).
Claude: Ustawienia → Connectors → Add custom connector → wklej adres.
ChatGPT: Settings → Connectors (tryb deweloperski) → dodaj serwer MCP.
Claude Code: claude mcp add --transport http szkoly https://szkoly.compabase.com/mcp
Lokalnie (stdio): npx -y szkoly-mcp, np. w Claude Desktop:
{ "mcpServers": { "szkoly": { "command": "npx", "args": ["-y", "szkoly-mcp"] } } }Related MCP server: PH Schools MCP Server
Narzędzie | Do czego |
| Szkoły albo przedszkola w miejscowości, gminie lub najbliżej adresu (z odległością): typ, publiczna/niepubliczna, specyfika (np. specjalna, sportowa), adres, liczba uczniów, strona www, numer RSPO i najnowsze wyniki egzaminu na tle Polski – egzamin ósmoklasisty dla podstawówek, zdawalność i średnie z matury dla liceów i techników. Sortowanie po odległości, wynikach albo nazwie; filtr „tylko publiczne”. |
| Jedna szkoła (po numerze RSPO albo nazwie): dane z rejestru, organ prowadzący, liczba uczniów i nauczycieli, wyniki z ostatnich 3 lat z każdego przedmiotu na tle powiatu i kraju – egzamin ósmoklasisty albo matura (zdawalność, przedmioty podstawowe i rozszerzone). |
| Źródła, roczniki danych i zastrzeżenia. |
Przykładowe pytania: „Jakie podstawówki są najbliżej ul. Garbary 10 w Poznaniu?”, „Najlepsze licea w Poznaniu wg matury”, „Porównaj SP 1 i SP 2 w Kórniku”, „Jakie przedszkola są w gminie Swarzędz?”, „Jak technikum w Bolesławcu wypada z matematyki na maturze?”.
Wykaz szkół i placówek oświatowych – MEN, System Informacji Oświatowej (stan na 30 września), dane.gov.pl, CC BY 4.0: ok. 42 tys. szkół i przedszkoli z adresem, typem, organem prowadzącym, liczbą uczniów i nauczycieli.
Wyniki egzaminów – Centralna Komisja Egzaminacyjna, Mapa wyników egzaminów: egzamin ósmoklasisty i matura (formuła 2023) z ostatnich 3 lat, dla każdej szkoły (średnie pokazywane od 5 zdających). Średnie powiatu i kraju liczymy z wyników szkół (ważone liczbą zdających).
Odległości – adresy szkół geokodowane państwowym rejestrem adresów GUGiK.
Dane pobierają się przy pierwszym uruchomieniu (~35 MB plików źródłowych, zapisywane jako ~35 MB JSON w ~/.cache/szkoly-mcp) i są sprawdzane raz na dobę.
Zastrzeżenia: wynik egzaminu zależy w dużej mierze od tego, jacy uczniowie trafiają do szkoły, i nie mierzy wszystkiego, co w niej ważne. O przyjęciu do szkoły podstawowej decyduje obwód (rejon) ustalony przez gminę.
npx -y szkoly-mcp --http --port 3000 # MCP: http://localhost:3000/mcp
npx -y szkoly-mcp find "Kórnik" --level podstawowa
npx -y szkoly-mcp school 70077Zmienne: SZKOLY_DATA_DIR, SZKOLY_REFRESH_HOURS (24), SZKOLY_E8_YEARS / SZKOLY_MATURA_YEARS (3), SZKOLY_RATE_LIMIT, SZKOLY_STATS=1 (anonimowe liczniki pod /stats), SZKOLY_CONTACT, SZKOLY_PUBLIC_URL.
Kod: MIT. Dane: MEN (SIO, dane.gov.pl, CC BY 4.0), CKE (Mapa wyników egzaminów), GUGiK – dane przetworzone. Projekt niezależny, hostowany pro publico bono przez Compabase. Zobacz też rozkład-mcp, ceny-nieruchomosci-mcp, leki-mcp i powietrze-mcp.
szkoly-mcp gives AI assistants the official register of Polish schools and kindergartens (Ministry of Education, SIO) with pupils, teachers and addresses, plus per-school exam results – the eighth-grade exam (egzamin ósmoklasisty) and the matura – for the last three years by subject, compared with county and national averages. Find schools in a town, gmina or near an address (with distances). Public endpoint: https://szkoly.compabase.com/mcp (no key), or run locally with npx -y szkoly-mcp.
Where the data comes from and caveats.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds essentially no behavioral context beyond that — it doesn't say whether this returns provenance metadata, a list, external references, or how large/stable the result is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is short with no wasted words, but it is a sentence fragment that is not front-loaded with a verb and reads as a caption rather than a definition. Brevity here reflects under-specification more than discipline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameters, the description is the only source of information about what this tool yields, and it does not explain the return content, structure, or the nature of the 'caveats'. For a metadata/provenance tool it leaves the agent guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies; there is no parameter semantics for the description to clarify.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a noun-phrase fragment ('Where the data comes from and caveats') that essentially restates the name and title. There is no verb and no statement of what the tool actually returns or does, so an agent cannot confidently distinguish it from siblings like air_quality or air_stations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Nothing indicates when to call this rather than air_quality or air_stations, nor any prerequisite or exclusion. Usage is at best implied by the word 'caveats', which is too weak to count as guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schools or kindergartens in a Polish town / gmina or near an address: type, public or non-public, address, number of pupils, RSPO id, website and the latest exam results (eighth-grade exam for primary schools, matura pass rate and averages for licea/technika) vs the national average. place: town "Kórnik", gmina, address "Kraków, Długa 5" (sorted by distance) or 'lat,lon'.
| Name | Required | Description | Default |
|---|---|---|---|
| max | No | How many to list (default 12) | |
| sort | No | Default: distance for addresses, results for school levels with exams | |
| level | No | przedszkole, podstawowa, liceum, technikum, branzowa, policealna, artystyczna or dowolna (default) | |
| place | Yes | Town, gmina, address or 'lat,lon' in Poland | |
| radius_km | No | Only within this distance from the address | |
| public_only | No | Only public schools |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds that results include exam results benchmarked against the national average and that address queries sort by distance, but it says nothing about result caps beyond the schema, rate limits, or coverage caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences: the first front-loads what the tool returns, the second documents the place input. No filler sentences, though the field enumeration makes the first sentence long and slightly run-on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the returned fields and the exam-result benchmarks, which is what an agent needs. It is nearly complete for a search tool, lacking only explicit guidance on sibling selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the 'place' formats (town, gmina, address, 'lat,lon') and the distance-sorting implication, but this largely duplicates the schema rather than adding new semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (find) and resource (schools and kindergartens in Poland), and enumerates the returned fields (type, address, pupil count, RSPO id, exam results). It is clearly distinguishable from school_details by its search/aggregation framing, though it never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the 'place' input patterns and the mention of sorting by distance. There is no explicit statement of when to call this versus school_details or data_sources, nor any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One school: register data (type, address, governing body, pupils, teachers, pupils per teacher) and exam results for the last years by subject – eighth-grade exam or matura (pass rate, basic and extended subjects) – compared with the county and national averages. school: RSPO number or name; town helps to disambiguate.
| Name | Required | Description | Default |
|---|---|---|---|
| town | No | Town or gmina | |
| school | Yes | RSPO number or school name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully adds that results are aggregated across 'the last years' and benchmarked against county and national averages, but it says nothing about coverage limits, data freshness, or behavior when a school cannot be resolved.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense sentence that front-loads the resource and then the payload contents, followed by a short parameter note. Every clause carries information, though the parenthetical field lists make it heavy to parse at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must carry the return-value burden, and it does so well by naming the register fields and exam-result dimensions returned. Remaining gaps are minor: no note on how many 'last years' are covered or what an empty/ambiguous match yields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema, and the description's restatement ('school: RSPO number or name; town helps to disambiguate') largely duplicates that. The only marginal addition is the disambiguation hint for town, which does not go beyond the schema's own 'Town or gmina' note in a meaningful way.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (a single school) and enumerates exactly what it returns: register data (type, address, governing body, pupils, teachers, pupils per teacher) and exam results with pass rates and county/national comparisons. The singular 'One school' implicitly contrasts with the plural search-oriented sibling find_schools, but that differentiation is never made explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit statement of when to use this tool versus find_schools or data_sources. Usage is only implied by the singular framing ('One school') and the note that 'town helps to disambiguate', which hints at a precise-lookup workflow without stating that the agent should resolve a school via find_schools first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0data_sourcesfind_schoolsschool_detailsScored across 3 tools
find_schools is clearly a search/list operation, school_details retrieves a single school's full profile, and data_sources provides provenance information. The three purposes are distinct with no meaningful overlap.
All names use consistent snake_case, but the pattern is mixed: find_schools uses a verb_noun form while school_details and data_sources are noun phrases. The deviation is minor and still readable.
Three tools are well-scoped for a focused school-search server: search, detail lookup, and data provenance. Each tool has a clear reason to exist, and the surface is not thin or bloated.
The core lifecycle—find schools with filters, inspect a specific school's detailed exam results, and check data caveats—is covered. Minor gaps like bulk listing or explicit town/gmina enumeration are not critical for the stated purpose.
Verified Polish open data for AI agents: debt, budget, 460 MPs, votings, judiciary search, RAG.
Polish company registry: 4.4M firms, KRS/REGON data, VAT white list checks, financial statements
Polish business register (REGON / BIR1.1) — resolve any Polish company by NIP, REGON or KRS number…
Find Polish companies (CEIDG, KRS, Google Maps), verify emails and run cold email campaigns from AI.
