AppyWay MCP server

An MCP server that lets Claude, ChatGPT and other MCP clients use the AppyWay API: UK kerbside parking rules and prices, parking entities (on-street bays and lines, car parks), controlled zones, local authorities and AppyWay's reference data. It is built from AppyWay's public documentation and its three published OpenAPI documents (Explorer, Traffic Data, Reference). Every tool is read-only.

Once it's connected, someone with an AppyWay API key can ask things like:

• "Can I park near 51.5195, -0.1100 between 6 and 8pm tonight, and what will it cost?"

• "I have a blue badge and an electric car. Where in this area can I park for the next two hours, and for how much?"

• "When do the single yellow lines in this controlled zone apply tomorrow?"

• "What are the operating hours of this bay on Saturday, and how do I pay for it?"

• "Which authorities does our key cover, and when were their traffic orders last updated?"

• "Give me the links to Northgate's full restriction data as it stood on 1 September."

Tools

Almost every AppyWay endpoint is a POST with a JSON body, but these POSTs are queries: they search or fetch and change nothing, which is why every tool carries the MCP readOnlyHint annotation. The API has no write endpoints in the published specs, so there is no write switch.

Not covered on purpose: the Traffic Data file exports (exportAuthorityRestrictions*.geojson, .dxf, exportAuthorityMovingRestrictionsById) and wfs, because they are downloads; fetchParkingQuotesByIds and fetchEventDatesById, which the tools above do not need. The Traffic Data spec defines schemas for traffic orders (Order, FullOrder, ...) but no endpoint that returns them, so there is no traffic-order tool; list_authorities reports each authority's lastTmoUpdate as last_traffic_order_update.

Related MCP server: ChurchSuite Bookings MCP

Setup

Requires Node 18 or later.

npm install
npm run build

You need an AppyWay API key. AppyWay's getting-started guide says keys are obtained from AppyWay by emailing apisupport@appyway.com; the key is sent in the API-KEY header. A key only covers the authorities it has been granted.

Claude Desktop: add this to claude_desktop_config.json:

{
  "mcpServers": {
    "appyway": {
      "command": "node",
      "args": ["/absolute/path/to/appyway-mcp/dist/index.js"],
      "env": { "APPYWAY_API_KEY": "your-key" }
    }
  }
}

Claude Code:

claude mcp add appyway -e APPYWAY_API_KEY=your-key -- node /absolute/path/to/appyway-mcp/dist/index.js

Safety defaults

• Read-only: every tool is a query and carries readOnlyHint: true and destructiveHint: false. There is no write tool and no write switch.

• No personal data is expected in this API. Still, telephone numbers (a payment provider's pay-by-phone number, a car park operator's number, the telephone on an authority note) are only returned when the assistant explicitly asks (include_contact_details); by default the output only says has_pay_by_phone: true. In free text (zone and authority notes and note titles, entity, zone and authority names, authority tags, entity address lines and location codes, reference-list names such as event venues, and AppyWay's own error messages, whatever the HTTP status) email addresses are replaced with [email redacted] and phone-number-like sequences with [phone redacted], using the same heuristic as the other servers in this series (international +/00 numbers including +44 (0)…, bracketed UK area codes, and 0… numbers of 9 to 11 digits; GUIDs, ETags and dates are left alone). include_contact_details returns the text unredacted. The heuristic only looks for emails and phone numbers. Ids, URLs (payment pages, app links, websites, note links) and the id/code/url fields of reference records are passed on as given.

• The Traffic Data Authority record contains an ordnanceSurvey object with an Ordnance Survey API key and licence. It is never returned, not even with include_contact_details.

• No bank, card or payment data exists in these endpoints. Payment-provider links (cardPaymentsExternalUrl, paymentsUrl) are the provider's own public payment pages and are returned; app deep links are returned per platform as given.

• Nothing is downloaded: get_authority_restrictions returns the four data-document links and never fetches them (AppyWay says they can be large; they are cached indefinitely and can be kept until the endpoint returns different links). Entity geometry is reduced to one WGS84 point (a Point without a CRS, or with EPSG:4326/CRS84); shapes and projected (EPSG:3857) coordinates are left out.

• Input is checked before any call is made: a location must be either lat+lng or a bbox, never both; the area limits AppyWay documents are enforced locally (1.5 km2 for parking and entity searches, so a square side of at most 1224 m; 300 km2 for authority searches); times must be ISO 8601 with a Z or an offset (a time given without seconds is sent with :00 added, since the specs document YYYY-MM-DDThh:mm:ssTZD), dates YYYY-MM-DD and real calendar dates (2026-02-30 is refused), and an end time after the start. Entity, zone and authority ids must be GUID-like strings (letters, digits, -, _, up to 64 characters, optionally wrapped in a pair of braces, which are removed before sending): the specs type them as plain strings, and every request example in AppyWay's guides is a bare GUID. Slugs must be letters, digits, - and _. Name filters (query) are trimmed, and one that is empty after trimming is refused.

• Operating-hours requests set the documented includeClosedPeriods: true, so the closed periods AppyWay has for that date are returned as closed_periods.

• Defaults: a parking window starts now and lasts one hour; a zone-rules window lasts 24 hours; operating hours are for today's UTC date; a square viewport is 300 m; a point given to list_authorities becomes a 100 m square. Ids sent to fetchEntitiesByIds and fetchOperatingHoursByIds go 50 per request; that cap is this server's choice (no maximum is documented).

• Rate limits: AppyWay documents a 429 Too many requests response on every operation but no limit, quota or Retry-After behaviour. Requests are spaced 250 ms apart (about four per second). A 429 is retried at most twice for any method (a rate-limited request was not processed), waiting for Retry-After (whole or fractional seconds, or an HTTP-date; 2 s then 4 s when the header is absent or unreadable). Each wait is capped at 10 seconds; if AppyWay asks for a longer wait, the call gives up at once and says how long to wait. A tool call that makes several requests can still run past the MCP client's default 60-second request timeout.

• 502, 503 and 504 are retried the same way for GET (the pings) only. A POST is never repeated after a gateway error, even though every POST here is a query; the error says it is safe to call the tool again. A GET that fails three times is reported with advice and without the gateway's HTML.

• A 200 whose body is not JSON (a proxy or login page in the way) or whose envelope says success: false is reported as an error, never as an empty result.

• Errors say what to do: a wrong key (401) names APPYWAY_API_KEY; the documented 401 for an authority outside the key's entitlement ("No permissions to authority …") says the key is not entitled to that authority and points to list_authorities and apisupport@appyway.com; a 403 says the key may not be enabled for that API section and suggests ping; 400 and 404 pass on AppyWay's message and per-field errors.

Tests

npm test

The test suite:

1. Validates every fixture record against the component schemas in AppyWay's three published OpenAPI documents (Explorer ParkingEntity, ParkingEntitySearchResult, Zone, ZoneSearchResult, Authority, ParkingEntityOperatingHoursResult, PaymentProvider; Traffic Data Authority, FullAuthority; Reference list responses), with negative controls. The specs are downloaded from Stoplight to spec-explorer.json, spec-traffic-data.json and spec-reference.json on the first run. Three adjustments are made so Ajv can use the documents, and the test says so in code: {"nullable": true} without a type (10 places) is read as "any value"; the OpenAPI 3.0 boolean exclusiveMinimum (once) is converted to the numeric form; and the Explorer Geometry schema, which lists only type and crs and forbids other keys, is allowed a coordinates array, because the Explorer guide's example entity has coordinates on every geometry (a check proves the unadjusted schema rejects the fixtures). The response of fetchFullAuthorityInfoBySlug is validated against a schema written by hand from the endpoint's description ("The initial object contains only the URLs"), because the published AuthoritySnapshotInfoDoc schema describes the documents behind the links, not the links; a check shows the published schema rejects a links-only response.

2. Starts a local mock of the API under /v1/explorer, /v1/traffic-data and /v1/reference that checks the API-KEY header and serves the fixtures (the API has no pagination). Its results are validated against each operation's documented response schema, and its errors against the documented shapes: 400 BadRequestResponse, 404 NotFoundResponse, and the getting-started guide's 401 example for an authority outside the key's entitlement. A wrong key and 429s get no body, as the specs document those responses with a description only. The Explorer guide's example search request is validated against the request schema and accepted by the mock. The enum names the server prints are checked against the specs' descriptions, and the TimeSpan parser against the documented [-][d.]hh:mm:ss[.fffffff] format and the spec's own example.

3. Starts the built server and drives it over stdio with the official MCP client: 21 checks covering tools/list and annotations (the same 8 read-only tools with APPYWAY_ALLOW_WRITES=true); every tool; the centre-and-size and polygon forms of the searches with every documented filter, vehicle detail, onStreetParkingTypes, includeNotApplicableTimes, maxDate and localeCode passed through exactly; the defaults (window, viewport, date); times without seconds sent with them; the 50-per-request batching of ids, braced ids sent bare and a repeated id reported once; includeClosedPeriods sent and the closed periods returned; an empty area making no follow-up calls; refusal of bad input before any call (two or no locations, inverted windows, bad ids, slugs, impossible dates, blank queries); the area limits just under and just over 1.5 km2 and 300 km2; redaction of emails and phone numbers in notes, note titles, entity, zone and authority names, tags, address lines, location codes and error messages (including a success: false 200) and the withholding of telephone numbers by default, and their return on request; a Point in EPSG:3857 left out; a data-document link given as a list passed on and an inline document summarised; the Ordnance Survey key never returned; the entitlement 401 and a 403 (on a GET and on a POST) reported with advice; a 404 for an unknown id; requests spaced about 250 ms apart; the 429 retry waiting for Retry-After in the seconds, fractional-seconds and HTTP-date forms and 2 s when the header is missing or unreadable, giving up after three attempts on a persistent 429 and at once on a Retry-After just above the 10 s cap (10.5 s); a 502 retried for GET and never for a POST; a GET failing three times with 503 reported without the gateway's HTML; a non-JSON 200 and a success: false envelope reported as errors; a wrong key; and that every request carried the API-KEY header and no other credential, hit a documented method and path, and sent a body that validates against the operation's documented request schema (or no body where none is documented).

All three parts (24 checks) run in about 45 seconds.

Status

This is a working prototype. It has not been run against the live API, because it was built without an AppyWay account (AppyWay offers no self-serve key or sandbox). Everything below is taken from the published specs and guides and should be confirmed on a real account:

• The error bodies for a wrong key (401), 403 and 429: the specs document them with a description only. The server handles any JSON message/errors[] and no body at all. Whether a 429 carries Retry-After, and what the rate limit is, are not documented.

• The entitlement error: the guide's 401 example ("No permissions to authority '{GUID}'", property authority). Which endpoints return it, and whether searches in an area outside the entitlement return it or just return fewer results, is not documented; the mock returns it for id and slug lookups.

• The body of GET /explorer/ping and GET /traffic-data/ping (not documented; the Reference ping documents {success, result: string}, and the description says "pong").

• The response of fetchFullAuthorityInfoBySlug: the schema describes FeatureCollections while the description says the object contains only URLs. The server passes on a string or a list of strings and summarises anything else without inlining it. Whether ospsUrl is one URL or several is not clear from the docs.

• Geometry: whether Explorer geometries carry coordinates (the schema omits them; the guide's example has them), and which CRS the Point uses when none is given (assumed WGS84, as in the guide's example; a point with another CRS is left out).

• The format of entity, zone and authority ids (all examples are GUIDs; the Traffic Data authority id is format: uuid), of slugs, and of country and region ids (up to 36 characters, as documented).

• Whether the list endpoints of the Reference API and fetchAllAuthorities accept a POST with no body (no request body is documented; that is what the server sends), and whether fetchAllRestrictionTypes accepts {} when no locale is given.

• The time window: the Explorer query schemas list endTime as optional but describe it as "Required"; the server always sends it. duration is read-only in the spec and is never sent. The format of requestedDuration in responses (a .NET TimeSpan per the guide) and how times are normalised.

• The operating hours returned when no date is sent (not documented); the server always sends one (today's UTC date by default, while AppyWay describes dates as local). What includeClosedPeriods adds on the live API, and the format of the closed periods' times (the spec's DateTimeRange example has no time zone), are not confirmed; the mock returns them only when the flag is set.

• The platform keys of paymentsAppDeepLinks (documented as a map "by platform" without naming the platforms) and whether paymentsTelephone is ever something other than a public pay-by-phone number.

• The area limits: the server enforces 1.5 km2 and 300 km2 with its own approximate area calculation for bounding boxes; AppyWay's own calculation may differ slightly at the edges. The documented viewportSize maximum on findParkingEntitiesByCentreAndViewportSize is 1225 m; the server allows at most 1224 m everywhere.

• Whether fetchEntitiesByIds and fetchOperatingHoursByIds accept 50 ids per request, or more (no maximum is documented).

• How many requests per second the API tolerates; the throttle here is a guess on the polite side.

Going to production

This version runs locally over stdio, with the key holder's own API key. For AppyWay's customers to connect from claude.ai or ChatGPT without handling keys, the next step is a remote server (Streamable HTTP) behind OAuth, hosted by AppyWay, and then a listing in the Claude and ChatGPT connector directories.

Licence

MIT. Built by Alexandru Dragoș (alexandru.dragos96@gmail.com) with an AI agent (Claude) working under his direction.