--- title: "Operator licence API and MCP server" canonical_url: https://haulierscope.co.uk/developers markdown_url: https://haulierscope.co.uk/developers.md dvsa_file_date: 2026-09-07 publisher: HaulierScope licence: Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/) --- # Operator licence API and MCP server > Free JSON API and MCP server for GB operator licence data: search, licences, companies, changes and public inquiries for apps and AI assistants. Source: DVSA operator licence data, file dated 7 September 2026 (https://www.data.gov.uk/dataset/2a67d1ee-8f1b-43a3-8bc6-e8772d162a3c/traffic-commissioners-goods-and-public-service-vehicle-operator-licence-records). Developers and AI assistants Look up any GB goods vehicle or PSV operator licence from your own code or from an AI assistant. The JSON API and the MCP server are free, need no key and return the same records as this website, with the DVSA file date and the source on every result. ## At a glance - MCP server (Streamable HTTP) https://haulierscope.co.uk/mcp - JSON API https://haulierscope.co.uk/api/v1 - OpenAPI 3.1 https://haulierscope.co.uk/openapi.json - Data DVSA file dated 7 September 2026 The data is the operator licence file that DVSA publishes as open data, read each time DVSA publishes a new file (usually weekly), with Companies House, DVSA earned recognition and Traffic Commissioner context. Read the [methodology](https://haulierscope.co.uk/methodology) for what each field means and [data status](https://haulierscope.co.uk/status) for the date of every source. ## MCP server The Model Context Protocol (MCP) lets an AI assistant call tools on another service. Our MCP server gives assistants such as Claude, ChatGPT, Cursor and VS Code direct, structured access to operator licence data. Ask a question in plain words, for example “Is OF2071131 valid, and how many vehicles does it authorise?”, and the assistant calls the right tool and cites the DVSA file date. - Address: `https://haulierscope.co.uk/mcp` - Transport: Streamable HTTP. Each request is answered with JSON; there are no sessions to manage. - Sign-in: none. All tools are read-only. - Server card: [https://haulierscope.co.uk/mcp/server-card](https://haulierscope.co.uk/mcp/server-card) ## Connect your assistant ### Claude Code ``` claude mcp add --transport http haulierscope https://haulierscope.co.uk/mcp ``` Add `--scope user` to use it in every project, or `--scope project` to share it through `.mcp.json`. ### Claude (claude.ai and Claude Desktop) Open Settings, then Connectors, and choose Add custom connector. Name it HaulierScope, paste `https://haulierscope.co.uk/mcp` as the URL and choose no sign-in. On Team and Enterprise plans an owner adds the connector for the organisation first. ### Cursor [Add HaulierScope to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=haulierscope&config=eyJ1cmwiOiJodHRwczovL2hhdWxpZXJzY29wZS5jby51ay9tY3AifQ==), or add this to `~/.cursor/mcp.json`: ``` { "mcpServers": { "haulierscope": { "url": "https://haulierscope.co.uk/mcp" } } } ``` ### VS Code (GitHub Copilot) [Add HaulierScope to VS Code](vscode:mcp/install?%7B%22name%22%3A%22haulierscope%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhaulierscope.co.uk%2Fmcp%22%7D), or add this to `.vscode/mcp.json`: ``` { "servers": { "haulierscope": { "type": "http", "url": "https://haulierscope.co.uk/mcp" } } } ``` ### ChatGPT Turn on developer mode (Settings, then Security and login), then add a new connector with the URL `https://haulierscope.co.uk/mcp` and no authentication. The server also has the `search` and `fetch` tools that deep research uses. ### OpenAI Codex, Gemini CLI and others ``` codex mcp add haulierscope --url https://haulierscope.co.uk/mcp gemini mcp add --transport http haulierscope https://haulierscope.co.uk/mcp ``` Any client that supports remote MCP servers over Streamable HTTP can use the same address. Older clients can bridge with `npx mcp-remote https://haulierscope.co.uk/mcp`. ### Test it from a terminal ``` npx @modelcontextprotocol/inspector --cli https://haulierscope.co.uk/mcp --transport http --method tools/list npx @modelcontextprotocol/inspector --cli https://haulierscope.co.uk/mcp --transport http \ --method tools/call --tool-name get_licence --tool-arg licence_number=OF2071131 ``` ## MCP tools Every tool is read-only and returns structured content with a published output schema, plus the same JSON as text. | Tool | Arguments | What it returns | | --- | --- | --- | | `search_operators` | `query, filters?, limit?` | Find operators by company name, licence number or company number. Filters: traffic area, goods or PSV, status, licence type, in the latest file. | | `get_licence` | `licence_number` | The full record of one licence: holder, type, status, vehicles, trailers, continuation date, operating centres, Companies House status, earned recognition, public inquiries, decisions and change history. | | `get_company` | `company_number` | Every licence of one company, with totals and its Companies House, Gazette and Traffic Commissioner context. | | `area_stats` | `area` | Licences, operators, vehicles, licence mix, largest operators and towns for one of the eight traffic areas. | | `recent_changes` | `release?, area?, change_type?, limit?, offset?` | What changed between one DVSA file and the one before, with before and after values. | | `upcoming_public_inquiries` | `area?` | Public inquiries the Traffic Commissioners have listed for companies, with date, venue, grounds and the official notice. | | `insolvency_watch` | `area?, limit?` | Licence holders that Companies House shows in liquidation, administration or receivership, with Gazette insolvency notices. | | `filing_watch` | `area?, limit?` | Licence holders whose accounts were overdue at the Companies House register date. | | `new_licences` | `month?, area?, limit?` | New operator licences granted in a month, from the Traffic Commissioners' weekly bulletins. | | `licences_ended` | `month?, area?, limit?` | Licences published as revoked, surrendered or terminated in a month, with the official heading and bulletin for each. | | `tc_decisions` | `area?, outcome?, limit?` | Traffic Commissioner regulatory decisions, with outcome, dates, appeal status and the decision document. | | `biggest_operators` | `kind, area?` | The biggest haulage companies or coach and bus operators by vehicles authorised, nationally or in one traffic area. | | `data_status` | `none` | The date and age of every source, and every DVSA file we hold. | | `search, fetch` | `query / id` | The search-and-fetch pair that ChatGPT deep research and company knowledge use. fetch returns the Markdown version of a page. | ## JSON API Plain HTTPS GET requests, JSON responses, no key. The full description is in [openapi.json](https://haulierscope.co.uk/openapi.json) (OpenAPI 3.1), which code generators and API tools can read directly. | Request | Returns | | --- | --- | | `GET /api/v1/search?q=wincanton` | Search by name, licence number or company number. Optional: area, category, status, licence\_type, in\_current\_file, limit. | | `GET /api/v1/licences/{licence_number}` | One licence. | | `GET /api/v1/companies/{company_number}` | One company and all its licences. | | `GET /api/v1/areas` | The eight traffic areas with licence and vehicle counts. | | `GET /api/v1/areas/{area}` | Statistics for one traffic area (slug, letter or name). | | `GET /api/v1/changes?release=YYYY-MM-DD` | Changes in one DVSA file. Optional: area, type, limit, offset. | | `GET /api/v1/public-inquiries?area=scotland` | Upcoming public inquiries for companies. | | `GET /api/v1/insolvency-watch?area=wales` | Licence holders in liquidation, administration or receivership, with Gazette notices. | | `GET /api/v1/filing-watch?area=wales` | Licence holders with accounts overdue at Companies House. | | `GET /api/v1/new-licences?month=YYYY-MM` | New operator licences granted in a month. Optional: area, limit. | | `GET /api/v1/licences-ended?month=YYYY-MM` | Licences revoked, surrendered or terminated in a month, in the official wording. Optional: area, limit. | | `GET /api/v1/tc-decisions?area=wales` | Traffic Commissioner decisions. Optional: outcome, limit. | | `GET /api/v1/rankings/haulage-companies?area=wales` | Biggest operators by vehicles authorised (haulage-companies or coach-and-bus-operators). | | `GET /api/v1/earned-recognition?area=wales` | DVSA earned recognition operators, by traffic area. | | `GET /api/v1/status` | Source dates and the DVSA files we hold. | ``` curl https://haulierscope.co.uk/api/v1/licences/of2071131 ``` A licence number is two letters and seven digits. The first letter is O for goods vehicles or P for buses and coaches; the second letter is the traffic area. Upper or lower case both work. ## What every response contains Every API response and every MCP tool result carries `source`, `file_date` (the date of the DVSA file the data describes), `canonical_url` (the page on this site), `markdown_url` and `attribution`. Quote the file date and link the canonical URL when you show the data. ``` { "source": "DVSA operator licence data (Traffic Commissioners' goods and public service vehicle operator licence records)", "file_date": "2026-09-07", "canonical_url": "https://haulierscope.co.uk/licence/of2071131", "markdown_url": "https://haulierscope.co.uk/licence/of2071131.md", "attribution": "Contains public sector information licensed under the Open Government Licence v3.0. Contains Companies House data.", "data": { "licence_number": "OF2071131", "licence_type": "Standard International", "status": "valid", "in_current_file": true, "vehicles_authorised": 2853, "trailers_authorised": 3604, "continuation_date": "2029-01-31", "holder": { "type": "company", "name": "WINCANTON HOLDINGS LIMITED", "company_number": "02155951", "operator_type": "Limited Company", "company_url": "https://haulierscope.co.uk/company/wincanton-holdings-limited-02155951" }, "traffic_area": "East of England", "…": "operating centres, Companies House, earned recognition, inquiries, decisions, history" } } ``` Errors use HTTP status codes (400, 404, 429, 503) and a JSON body with an `error.code` and a plain-English `error.message`. ## Markdown versions of pages Every public page has a clean Markdown version for language models. Add `.md` to the address, for example [/area/scotland.md](https://haulierscope.co.uk/area/scotland.md) or [/index.md](https://haulierscope.co.uk/index.md) for the home page, or request the normal address with the header `Accept: text/markdown`. Each version starts with a one-paragraph answer and the source and date, and links to the normal pages. Browsers and search engines always get the normal page. ``` curl -H "Accept: text/markdown" https://haulierscope.co.uk/guides/vet-a-haulier ``` ## Discovery files - [/llms.txt](https://haulierscope.co.uk/llms.txt): a short map of the site for language models. - [/llms-full.txt](https://haulierscope.co.uk/llms-full.txt): the guides, methodology and data documentation in one file. - [/okf/index.md](https://haulierscope.co.uk/okf): the same knowledge as an Open Knowledge Format bundle of linked Markdown files. - [/openapi.json](https://haulierscope.co.uk/openapi.json) and [/.well-known/api-catalog](https://haulierscope.co.uk/.well-known/api-catalog): the API description and its catalogue entry. - [/mcp/server-card](https://haulierscope.co.uk/mcp/server-card) and [/.well-known/ai-catalog.json](https://haulierscope.co.uk/.well-known/ai-catalog.json): the MCP server card and the site’s AI catalogue. ## Rules for using the data - **Attribution.** Licence data is open data under the Open Government Licence v3.0. Show “Contains public sector information licensed under the Open Government Licence v3.0.” with it, and “Contains Companies House data.” when you show company facts. - **Privacy.** We never hold director, partner or transport manager names or correspondence addresses. Sole traders and partnerships are people: they are never named here, they are found only by exact licence number, and their records are minimal. Do not use the data to identify them. See the [privacy notice](https://haulierscope.co.uk/privacy). - **Wording.** A licence that is not in the latest DVSA file is “not in the DVSA file dated” that date: the file does not say why. The status “unmapped” is not valid. The continuation date is not an expiry date. - **Independence.** HaulierScope is independent and is not the official register. For the official record, use the GOV.UK service “Find lorry or bus operators”. ## Rate limits and caching Each connection can make 60 requests at once, then one request a second. The response headers `X-RateLimit-Limit` and `X-RateLimit-Remaining` show where you are; over the limit, you get HTTP 429 with a `Retry-After` header. Sole-trader and partnership licences have a lower hourly limit, the same as their web pages. Most responses can be cached for five minutes; the data changes when DVSA publishes a new file, so caching for longer is fine for most uses. Need higher volumes, a bulk list check or alerts when a licence changes? That is what [monitoring](https://haulierscope.co.uk/monitoring) is for. Questions: [contact us](https://haulierscope.co.uk/contact). --- Canonical page: https://haulierscope.co.uk/developers Contains public sector information licensed under the Open Government Licence v3.0. Contains Companies House data. HaulierScope is an independent service, not affiliated with DVSA or the Traffic Commissioners. It is updated when DVSA publishes a new file, usually weekly.