What can you do with this server?

The hut-reservation-mcp server lets AI agents search, check availability, and manage reservations for Swiss Alpine Club (SAC) huts on hut-reservation.org, with a write-safe design that prevents accidental bookings. * Check auth status: Report the readiness of credentials, hut catalog, geocoder, and caches — no login required. * Search huts: Find huts from the bundled catalog by text, country, canton, or proximity to GPS coordinates — no login required. * Check availability: Look up free places for specific arrival/departure dates and party size across matched huts — no login required. * Refresh hut catalog: Pull the latest hut metadata from hut-reservation.org into the local cache — requires authentication. * Refresh area cache: Reverse-geocode hut coordinates to populate canton/country filters using a configured Nominatim-compatible geocoder — requires geocoder setup. * Prepare a booking: Create a short-lived booking draft without confirming — requires authentication. * Confirm a booking: Finalize a prepared booking draft; by default returns a browser handoff URL for manual confirmation rather than writing upstream directly — requires authentication. * List reservations: View your upcoming or past hut reservations — requires authentication. * Prepare a cancellation: Fetch reservation details and create a cancellation draft — requires authentication. * Confirm a cancellation: Finalize a cancellation draft; returns a browser handoff URL by default — requires authentication.

Which integrations are available for this server?

Provides reverse geocoding via a Nominatim-compatible service to refresh canton and country area data for hut searches.

How do I use hut-reservation-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hut-reservation-mcp search for huts near Zermatt within 5 km" 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.

hut-reservation-mcp

by domwoe

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

🏔️ hut-reservation MCP

Find, check, and book Swiss Alpine Club (SAC) huts straight from your AI agent — write-safe by default.

npm version npm downloads license MCP

A Model Context Protocol server that gives any MCP-capable agent (Claude, Codex, Cursor, …) the ability to search huts on hut-reservation.org, check exact-date availability, and prepare bookings and cancellations.

Ask your agent things like:

"Find huts within 20 km of Zermatt that have space for 2 people on 12 July."
"Is the Cabane du Mont Fort free next weekend?"
"Draft a booking for the Britanniahütte for 2 nights and give me the confirmation link."
"List my upcoming hut reservations."

Why write-safe? Bookings and cancellations never fire blind. By default the server prepares a draft and hands you a browser URL to confirm the final step yourself — so an agent can do all the searching and legwork without the risk of an accidental, hard-to-reverse reservation. Confirmed upstream writes are opt-in. See Safety model.

Quick start

npx hut-reservation-mcp

The server speaks MCP over stdio, so you normally don't run it by hand — you point your MCP client at it and let the client spawn it. Pick your client below.

claude mcp add hut-reservation -- npx -y hut-reservation-mcp

Restart Claude Code after adding so the server is respawned, then check /mcp.

Add this to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "hut-reservation": {
      "command": "npx",
      "args": ["-y", "hut-reservation-mcp"]
    }
  }
}

Restart Claude Desktop after editing the file.

codex mcp add hut-reservation -- npx -y hut-reservation-mcp

Codex stores the server in config.toml. Start a new Codex session (MCP tools aren't injected into a running turn), then confirm with /mcp in the TUI.

Most clients accept a config of this shape:

{
  "mcpServers": {
    "hut-reservation": {
      "command": "npx",
      "args": ["-y", "hut-reservation-mcp"],
      "env": {
        "HUT_RESERVATION_CACHE_DIR": "$HOME/.cache/hut-reservation-mcp"
      }
    }
  }
}

The package ships with a bundled hut catalog so search_huts and search_hut_availability work immediately without logging in. Availability lookups are also unauthenticated. You'll get a warning in results that the bundled catalog may be stale — run refresh_hut_catalog with credentials to update it. Booking, cancellation, listing your reservations, and refreshing the catalog require authentication. See Configuration & authentication.

Related MCP server: HemmaBo

Tools

All tool-facing dates use ISO YYYY-MM-DD. The server translates to the upstream Swiss DD.MM.YYYY format internally.

Tool	Purpose	Auth required	Writes?
`auth_status`	Report login, catalog, geocoder, area-cache, and draft-cache readiness. Run this first when diagnosing setup.	No	—
`search_huts`	Search cached huts by text, country, canton, or distance around coordinates. Uses bundled catalog if no local cache.	No¹	—
`search_hut_availability`	Search exact-period availability for matched huts. Availability lookups are unauthenticated.	No¹	—
`refresh_hut_catalog`	Refresh cached hut metadata from the upstream hut list. Replaces the bundled catalog with fresh data.	Yes	—
`refresh_area_cache`	Refresh canton/country area data via a reverse geocoder. Needs `NOMINATIM_BASE_URL`, not login.	No²	—
`prepare_booking`	Create a safe booking draft (does not confirm).	Yes	—
`confirm_booking`	Confirm a prepared booking, or return a browser handoff URL.	Yes	⚠️
`list_bookings`	List your reservations via the authenticated endpoint.	Yes	—
`prepare_cancellation`	Create a safe cancellation draft (does not confirm).	Yes	—
`confirm_cancellation`	Confirm a prepared cancellation, or return a browser handoff URL.	Yes	⚠️

¹ Works without credentials using the bundled catalog. Results include a staleness warning; run refresh_hut_catalog with credentials to update. ² Requires a configured Nominatim-compatible geocoder (NOMINATIM_BASE_URL), but no hut-reservation.org login.

⚠️ Confirmation tools return a browser handoff URL by default. They only perform a real upstream write when experimental writes are explicitly enabled and a raw payload is supplied.

search_hut_availability checks every matched hut by default. Set maxCandidates only when you intentionally want a faster partial search; partial responses include truncated, totalCandidates, checkedCandidates, and a warning.

Suggested workflows

Find huts with availability (no login needed for steps 1–2)

search_huts → 2. search_hut_availability. The bundled catalog is used automatically if no local cache exists; watch for the staleness warning.
Optionally: authenticate → refresh_hut_catalog → repeat for the latest hut list.
For canton filters: configure a reverse geocoder → refresh_area_cache (no login needed).

Prepare a booking

Search huts + availability → 2. prepare_booking → 3. review the draft → 4. confirm_booking → 5. complete the browser handoff (unless experimental writes are enabled).

Prepare a cancellation

Authenticate → 2. list_bookings → 3. prepare_cancellation → 4. review the draft → 5. confirm_cancellation → 6. complete the browser handoff (unless experimental writes are enabled).

Safety model

High-risk upstream writes are intentionally conservative. The public SPA exposes preBook, submit, myReservations, reservationSummary, delete/{id}, and partial-cancellation-fee endpoints, but the full booking-form payload is not documented — so blind automated writes would be fragile and risky.

By default, confirm_booking and confirm_cancellation return a browser handoff URL instead of writing. A real write requires both:

HUT_RESERVATION_EXPERIMENTAL_WRITES=true, and
a caller-supplied raw payload.

Treat session cookies, XSRF tokens, passwords, and raw booking payloads as bearer credentials. Keep them in ignored local files, your MCP client's env config, or a secret manager. Never commit them.

Configuration & authentication

Do I need to authenticate?

No — searching works out of the box. The package bundles a hut catalog, and hut availability is a public endpoint, so you can find huts and check dates with zero setup. Add credentials only when you want fresher data or to touch your own reservations.

What you want to do	Tools	Credentials
Search huts & check availability	`search_huts`, `search_hut_availability`	Not needed (uses the bundled catalog)
Update the catalog to the latest hut list	`refresh_hut_catalog`	Required
Get canton filters	`refresh_area_cache`	Not needed — but requires a geocoder
List your reservations	`list_bookings`	Required
Prepare / confirm a booking or cancellation	`prepare_booking`, `confirm_booking`, …	Required

The bundled catalog only changes when huts open, close, or get renamed — rarely. Search results flag when it's getting old so your agent can suggest a refresh_hut_catalog.

Which auth mode?

⚠️ If you log in to hut-reservation.org via the Swiss Alpine Club (i.e. your account is an SAC account), you must use sac mode. The standard username/password flow only works for native hut-reservation.org accounts; an SAC-linked email will authenticate but the session is rejected as "Invalid Session". When in doubt, use sac.

standard — a native hut-reservation.org account (username + password):

HUT_RESERVATION_AUTH_MODE=standard
HUT_RESERVATION_USERNAME=person@example.com
HUT_RESERVATION_PASSWORD=...

sac — an SAC account, via browser-session cookies. Log in at hut-reservation.org through SAC in your browser, then open DevTools → Application → Cookies → https://www.hut-reservation.org and copy the SESSION and XSRF-TOKEN values:

HUT_RESERVATION_AUTH_MODE=sac
HUT_RESERVATION_SESSION_COOKIE=...
HUT_RESERVATION_XSRF_TOKEN=...
# or, equivalently, both in one header:
# HUT_RESERVATION_COOKIE_HEADER="SESSION=...; XSRF-TOKEN=..."

SAC cookies expire — when catalog refresh starts failing with an auth error, grab fresh cookie values from the browser.

Setting these variables with the `npx` install

Because your MCP client (not your shell) spawns the server, set credentials in the client config rather than relying on a shell environment. Two options:

1. Inline in the client's env block (or -e KEY=val with claude mcp add):

{
  "mcpServers": {
    "hut-reservation": {
      "command": "npx",
      "args": ["-y", "hut-reservation-mcp"],
      "env": {
        "HUT_RESERVATION_AUTH_MODE": "sac",
        "HUT_RESERVATION_SESSION_COOKIE": "...",
        "HUT_RESERVATION_XSRF_TOKEN": "..."
      }
    }
  }
}

2. Point at a .env file by absolute path — keeps secrets out of the client config:

"env": { "HUT_RESERVATION_DOTENV_PATH": "/Users/me/.config/hut-reservation/.env" }

The server auto-loads .env from its working directory too, but under npx that directory is unpredictable, so prefer HUT_RESERVATION_DOTENV_PATH. Values from the env block override values from the .env file. See .env.example for a template, and treat cookies, tokens, and passwords as secrets — never commit them.

All environment variables

Variable	Description
`HUT_RESERVATION_AUTH_MODE`	`standard` (username/password) or `sac` (browser-session cookies).
`HUT_RESERVATION_USERNAME` / `HUT_RESERVATION_PASSWORD`	Standard `hut-reservation.org` credentials.
`HUT_RESERVATION_SESSION_COOKIE` / `HUT_RESERVATION_XSRF_TOKEN`	SAC `SESSION` and `XSRF-TOKEN` cookie values.
`HUT_RESERVATION_COOKIE_HEADER`	Combined cookie header, e.g. `SESSION=...; XSRF-TOKEN=...`.
`HUT_RESERVATION_CACHE_DIR`	Cache directory. Defaults to `~/.cache/hut-reservation-mcp`.
`HUT_RESERVATION_REQUEST_TIMEOUT_MS`	Upstream request timeout (ms). Default `15000`.
`HUT_RESERVATION_EXPERIMENTAL_WRITES`	`true` to allow raw-payload confirmed writes. Default `false`.
`HUT_RESERVATION_DOTENV_PATH` / `HUT_RESERVATION_DOTENV_DISABLED`	Point at a specific `.env`, or disable dotenv loading.
`NOMINATIM_BASE_URL`	Reverse geocoder base URL. Required before `refresh_area_cache` can geocode.
`NOMINATIM_USER_AGENT` / `NOMINATIM_EMAIL` / `NOMINATIM_MIN_INTERVAL_MS`	Identifying User-Agent, contact email, and rate limit for geocoder requests.

Reverse geocoder (optional, for canton filters)

NOMINATIM_BASE_URL=https://your-nominatim.example
NOMINATIM_USER_AGENT="hut-reservation-mcp/0.1.0 you@example.com"
NOMINATIM_MIN_INTERVAL_MS=1000

The server never uses public Nominatim implicitly. Configure an explicit provider and identifying User-Agent before calling refresh_area_cache. Follow the provider's usage policy, cache responses, and preserve OpenStreetMap attribution.

Troubleshooting

Symptom	Fix
Search results include a stale bundled catalog warning	The bundled catalog is being used. Run `refresh_hut_catalog` with valid credentials to populate a local up-to-date copy.
`refresh_hut_catalog` fails with "Full authentication is required"	You're not authenticated. Configure credentials; the catalog endpoint is auth-gated.
Auth fails with "Invalid Session"	Your account is likely an SAC account — switch to `sac` mode with fresh browser cookies, or your SAC cookies have expired.
Canton filters return nothing	Configure a Nominatim-compatible geocoder, then run `refresh_area_cache`.
Availability searches are slow	Narrow your search filters first, or set `maxCandidates` for an intentional partial search.
Authenticated tools fail	Check `HUT_RESERVATION_AUTH_MODE` and credentials, then restart the client so it respawns the server with the new env.
Codex doesn't see the tools	Start a new Codex session (or reload), then check `/mcp`.
Confirmation returns a browser URL	Expected — unless `HUT_RESERVATION_EXPERIMENTAL_WRITES=true` and a raw payload are supplied.

Develop from source

git clone https://github.com/domwoe/hut-reservation-mcp.git
cd hut-reservation-mcp
pnpm install
pnpm dev          # run over stdio from TypeScript source

Point a client at your local checkout:

claude mcp add hut-reservation -- pnpm --dir /absolute/path/to/hut-reservation-mcp dev
# or, for the built entrypoint:
pnpm build
claude mcp add hut-reservation -- node /absolute/path/to/hut-reservation-mcp/dist/index.js

Regenerating the bundled catalog

The package ships data/catalog.json so users can search without authenticating. Regenerate it before releasing a new version:

# Requires valid credentials in .env (standard or sac mode)
pnpm generate:catalog
# then commit data/catalog.json and bump the version

The hut catalog changes rarely (new huts open, names change). Regenerating once per release is sufficient.

Verification

pnpm typecheck
pnpm test
pnpm run smoke:mcp:source
pnpm build
pnpm run smoke:mcp:dist

Optional read-only live smoke test against upstream:

HUT_RESERVATION_LIVE_SMOKE=true pnpm smoke:read

Disclaimer

This is an unofficial, community project and is not affiliated with the Swiss Alpine Club (SAC) or hut-reservation.org. Use it responsibly and in line with the site's terms of service.

Available Tools

10 tools

auth_statusAuth StatusA

Read-onlyIdempotent

Report whether hut-reservation.org credentials and an upstream session are available.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context about checking credentials and session but does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, 10 words, front-loaded with the verb 'report'. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and rich annotations, the description sufficiently explains the tool's purpose and what it reports, making it complete for an auth status check.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters, baseline is 3 due to high schema coverage. However, the description adds meaning by specifying what is checked (credentials and session), enhancing understanding beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports availability of credentials and upstream session, which is specific and distinct from siblings (bookings, hut search, etc.). Not a tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives, but its purpose is implied by its name and unique functionality among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

confirm_bookingConfirm BookingA

Destructive

Confirm a prepared booking draft. Headless submit only runs when experimental writes are enabled and the draft contains a raw upstream payload.

ParametersJSON Schema

Name	Required	Description	Default
`draftId`	Yes

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is destructive (destructiveHint=true) and not read-only. Description adds beyond annotations by specifying prerequisites for headless submit, which is non-obvious behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with main action. Some technical jargon ('headless submit', 'raw upstream payload') but still efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet description omits what the tool returns on success or failure. Given only one parameter, more detail about expected outcomes or side effects is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and description does not explain the single parameter 'draftId' beyond its name. The description adds no semantic detail about the parameter's format, purpose, or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Confirm' and resource 'prepared booking draft'. Distinguishes from siblings like 'prepare_booking' and 'confirm_cancellation' by specifying it operates on a draft.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides condition 'Headless submit only runs when experimental writes are enabled and the draft contains a raw upstream payload', which guides when the tool works. Lacks explicit alternatives or when-not scenarios, but the context is helpful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

confirm_cancellationConfirm CancellationA

Destructive

Confirm a cancellation draft. This currently returns a browser handoff because confirmed-reservation cancellation semantics are not verified.

ParametersJSON Schema

Name	Required	Description	Default
`draftId`	Yes

TDQS

A3.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by disclosing the output ('browser handoff') and the incomplete semantics, which warns the agent about unexpected behavior. Annotations already indicate destructiveHint=true, so no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the primary purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description does not indicate what the 'browser handoff' entails (e.g., a redirect URL) nor prerequisites like a valid cancellation draft. Given no output schema and a destructive action, more guidance is needed for safe usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fails to explain the 'draftId' parameter, its purpose, or how to obtain it. The single parameter is left entirely undocumented, forcing the agent to infer from the parameter name and pattern.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Confirm a cancellation draft,' specifying the action (confirm) and resource (cancellation draft). It distinguishes from siblings like 'prepare_cancellation' and 'confirm_booking'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context about the tool's limitation ('returns a browser handoff' and 'semantics not verified'), but does not explicitly state when to use this tool vs alternatives or give usage guidelines like prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_bookingsList BookingsC

Read-only

List authenticated user's reservations through hut-reservation.org myReservations.

ParametersJSON Schema

Name	Required	Description	Default
`researchFilter`	No
`open`	No
`dateFrom`	Yes
`dateTo`	Yes
`page`	No
`size`	No
`sortList`	No
`sortOrder`	No
`profiId`	No

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds only that it lists the user's own reservations, implying authentication. With annotations providing readOnlyHint, there is no contradiction, but no further behavioral context (e.g., pagination, rate limits) is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise (one sentence) and front-loaded, but it omits necessary detail for a tool with nine parameters, making it under-informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (9 parameters, no output schema), the description is incomplete. It does not explain output format, filtering behavior, or how parameters like open and sortList work.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no explanation for any of the nine parameters. The meaning of fields like researchFilter, open, sortList remains unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'authenticated user's reservations' from 'myReservations', distinguishing it from sibling tools like search_huts or confirm_booking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing the user's own bookings but provides no explicit guidance on when to use this tool versus alternatives such as search_hut_availability or auth_status.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

prepare_bookingPrepare BookingA

Check availability and create a short-lived booking draft. By default this returns a browser handoff URL rather than writing upstream.

ParametersJSON Schema

Name	Required	Description	Default
`hutId`	Yes
`arrivalDate`	Yes
`departureDate`	Yes
`partySize`	Yes
`guestData`	No
`rawReservationPayload`	No

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds that the tool creates a draft and returns a browser handoff URL, going beyond annotations which only mark it as non-read-only and non-destructive. However, it does not detail the draft's lifespan or next steps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no redundancy; front-loads the core purpose and behavioral nuance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters and no output schema, the description is too sparse. It lacks info on draft expiration, URL format, or error cases, which are important for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not explain any parameters, leaving the agent to infer their meaning from names alone. The description should at least summarize key parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks availability and creates a short-lived booking draft, distinguishing it from confirmation tools like confirm_booking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains that by default it returns a handoff URL rather than writing upstream, but does not explicitly contrast with search_hut_availability or clarify when to use this versus other booking-related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

prepare_cancellationPrepare CancellationA

Fetch reservation summary/fee context and create a short-lived cancellation draft. Confirmed cancellation remains browser-handoff only.

ParametersJSON Schema

Name	Required	Description	Default
`reservationPublicId`	Yes
`reservationId`	No
`newArrivalDate`	No
`newDepartureDate`	No
`newPeopleNumber`	No

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by stating that the cancellation draft is 'short-lived' and that confirmed cancellation requires browser handoff. Annotations already indicate non-readonly and non-destructive behavior, and the description aligns with those. Some behaviors (e.g., expiration time, error handling) are omitted but acceptable for a simple tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two sentences, with the first sentence immediately stating the main action. No extraneous information. Very efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description should mention the return value (e.g., draft ID or status). It also lacks detail on parameter usage. It is too brief for an agent to fully understand the tool's behavior without additional documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description provides no explanation of the parameters, especially the optional ones (newArrivalDate, newDepartureDate, newPeopleNumber), which seem to conflict with the 'cancellation' focus. The agent cannot infer their purpose from the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Fetch' and 'create') and clearly identifies the resource (reservation cancellation draft). It distinguishes from the sibling tool 'confirm_cancellation' by noting that confirmed cancellation remains browser-handoff only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly guides usage by stating that confirmed cancellation is not handled by this tool, implying it is only for preparation. However, it does not explicitly list when to use this versus other similar tools like confirm_cancellation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refresh_area_cacheRefresh Area CacheB

Reverse-geocode cached hut coordinates through the configured Nominatim-compatible provider. Requires explicit geocoder configuration.

ParametersJSON Schema

Name	Required	Description	Default
`force`	No
`limit`	No

TDQS

B3.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds the behavioral trait that it requires explicit geocoder configuration, which is beyond the annotations. However, it doesn't disclose mutation details or error states, though annotations already indicate non-read-only.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no filler. Every word adds value. Front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With two parameters and no output schema, the description should compensate but only provides a high-level purpose and a prerequisite. Missing parameter docs and return value explanation make it incomplete for effective tool use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No description coverage in the schema (0%) and the tool description does not explain the meaning of 'force' or 'limit' parameters. Agents cannot infer correct usage from the description alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (reverse-geocode), resource (cached hut coordinates), and context (through Nomination-compatible provider). It distinguishes from siblings like refresh_hut_catalog which updates a different resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like refresh_hut_catalog. Only mentions a prerequisite (explicit geocoder configuration) but no usage context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

refresh_hut_catalogRefresh Hut CatalogA

Fetch hut-reservation.org hut list and hut details into the local cache. This performs read-only upstream calls and mutates only the local cache.

ParametersJSON Schema

Name	Required	Description	Default
`country`	No
`limit`	No

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds context beyond annotations: explains upstream calls are read-only and local cache mutation. This clarifies the read-only annotation false (mutation is local). No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each earning its place: first states action, second clarifies behavioral boundaries. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple refresh operation but lacks mention of prerequisites (e.g., network access), error handling, or connection to sibling tools (e.g., search_huts depends on this cache). With no output schema, impacts of failures are unclear.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Description provides no information about the two parameters (country, limit) beyond what's in the schema, which has 0% coverage. Agent must infer meaning from names alone, which could be ambiguous (e.g., country format).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it fetches hut list and details from hut-reservation.org into local cache, distinguishing it from sibling tools like refresh_area_cache (different resource) and search_huts (query vs refresh). The verb 'refresh' and resource 'hut catalog' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for refreshing local cache but lacks explicit guidance on when to use vs alternatives (e.g., search_huts for queries) or prerequisites. No mention of context like 'call before searching for availability'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_hut_availabilitySearch Hut AvailabilityA

Read-only

Search huts with enough free places for every night in an exact arrival/departure period. Tool dates are ISO YYYY-MM-DD. By default all matched cached huts are checked; maxCandidates intentionally returns a partial result.

ParametersJSON Schema

Name	Required	Description	Default
`country`	No
`canton`	No
`text`	No
`near`	No
`arrivalDate`	Yes
`departureDate`	Yes
`partySize`	Yes
`limit`	No
`maxCandidates`	No

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only (readOnlyHint=true) and open-world (openWorldHint=true). The description adds valuable behavioral context: it checks cached huts by default and that 'maxCandidates' yields partial results. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with the core purpose front-loaded. Every sentence adds information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite annotations providing some context, the description is insufficient for a tool with 9 parameters, including a nested 'near' object. It does not explain return behavior, result structure, or how to interpret the output, which is critical given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It only mentions 'ISO YYYY-MM-DD' for dates (implicitly for arrivalDate and departureDate) and 'maxCandidates'. The remaining parameters (country, canton, text, near, limit, partySize) are not described, leaving their semantics unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search') and resource ('huts') with a clear constraint ('enough free places for every night in an exact arrival/departure period'). It distinguishes itself from the sibling 'search_huts' by focusing on availability checking for a date range.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies date format (ISO YYYY-MM-DD) and explains default behavior (all matched cached huts checked) and the effect of 'maxCandidates' (intentional partial result). However, it does not explicitly state when to use this tool versus alternatives like 'search_huts', though the context implies it for availability queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_hutsSearch HutsA

Read-onlyIdempotent

Search cached huts by country, canton cache, text, and/or distance around coordinates. Does not call a geocoder during search.

ParametersJSON Schema

Name	Required	Description	Default
`country`	No
`canton`	No
`text`	No
`near`	No
`limit`	No
`offset`	No

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is clear. The description adds value by revealing it searches 'cached' data and does not call a geocoder, which impacts latency and data freshness. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no unnecessary words. The first sentence states the core functionality; the second adds a critical behavioral caveat. Every part earns its place, and the structure is front-loaded with the primary purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters, nested objects, and no output schema, the description is incomplete. It does not mention the output format (e.g., list of huts), pagination behavior (limit/offset), or constraints like max radius. The tool is moderately complex, and the description leaves significant gaps for an agent to handle correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the purpose of 4 out of 6 parameters (country, canton, text, near) but omits limit and offset. It adds some meaning beyond the schema (e.g., 'canton cache' for canton, 'distance around coordinates' for near), but does not fully cover all parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches cached huts using specific filters (country, canton, text, distance), providing a specific verb and resource. It also notes the tool does not use a geocoder, adding extra clarity. The purpose is well-differentiated from sibling tools like search_hut_availability.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like search_hut_availability or list_bookings. The description lacks usage context, exclusions, or suggestions for when this tool is preferred. An agent would need to infer usage based solely on the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

10 tool updatesv0.1.0Jun 18, 2026
- First observedauth_status
- First observedconfirm_booking
- First observedconfirm_cancellation
- First observedlist_bookings
- First observedprepare_booking
- First observedprepare_cancellation
- First observedrefresh_area_cache
- First observedrefresh_hut_catalog
- First observedsearch_hut_availability
- First observedsearch_huts

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored 2026-06-18 22:40 across 10 tools

Disambiguation5/5

Each tool targets a distinct operation: authentication, booking/cancellation lifecycle (prepare vs confirm), hut searching (by criteria vs availability), cache refreshing, and listing. No two tools have overlapping purposes.

Naming Consistency4/5

Most tools follow a 'verb_noun' pattern (e.g., confirm_booking, search_huts), but auth_status deviates as a noun_noun. Otherwise naming is consistent and clear.

Tool Count5/5

With 10 tools, the server is well-scoped for managing hut reservations. Each tool serves a distinct need without redundancy or excess.

Completeness3/5

Covers the core reservation flow (search, draft, confirm, cancel, list) and caching. However, lacks tools for modifying a booking or retrieving a single booking's details, which are notable gaps.

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

Hüttentouren A
org.huettentouren
Hut-to-hut hiking tours in the Alps with live availability from multiple booking systems.
Travel & Transportation Search
32
outdoorithm A
io.github.outdoorithm
Campground discovery, availability, planning, and booking handoffs across US public lands.
Travel & Transportation Location Services Government Data
132
Caboo A
com.getcaboo
Find local services, read availability, and create short-lived booking holds.
E-commerce & Retail Calendar Management Location Services
2
acuity-scheduling A
io.usefulapi
Read appointments, types, calendars and availability; create, cancel or reschedule bookings.
Calendar Management Workplace & Productivity
182

Related MCP Servers

Flight + Stay Search MCP
Travel & Transportation E-commerce & Retail Search
AkekaratP
F
license
C
quality
C
maintenance
Enables searching for flights (one-way, round-trip, multi-city) and hotels using the Duffel API, with support for filtering by cabin class, passengers, dates, and viewing accommodation reviews.
Updated a year ago (2025-05-06 06:37 UTC)
5
-
HemmaBo
E-commerce & Retail Finance Travel & Transportation
HemmaBo-se
A
license
A
quality
A
maintenance
Search vacation rental properties, check real-time availability, get canonical pricing quotes, and create direct bookings. Each property is its own node with live data. Supports staircase pricing, seasonal rates, and 11 languages.
Updated 2 days ago (2026-09-11 01:21 UTC)
4
13
218 npm
3
Apache 2.0
reservations-mcp
Search Location Services
kunalkhosla
A
license
A
quality
C
maintenance
Enables restaurant discovery and reservations across multiple providers (Resy, Google Places, Yelp, Tock) with auditable and secure two-step booking.
Updated 2 months ago (2026-06-29 14:58 UTC)
10
MIT
mcp-camptocamp
Sports Location Services
olaurendeau
A
license
A
quality
B
maintenance
Exposes the Camptocamp.org API to LLMs, enabling querying of alpine routes, summit altitudes, and course descriptions with reliable data to avoid hallucinations.
Updated 2 months ago (2026-07-14 19:16 UTC)
6
74 npm
1
MIT

🏔️ hut-reservation MCP

Quick start

Tools

Suggested workflows

Safety model

Configuration & authentication

Do I need to authenticate?

Which auth mode?

Setting these variables with the npx install

All environment variables

Reverse geocoder (optional, for canton filters)

Troubleshooting

Develop from source

Regenerating the bundled catalog

Verification

Disclaimer

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Setting these variables with the `npx` install