Skip to Content
Bins MCP Server

Use the Bins MCP Server

This document describes the Streamable HTTP MCP (Model Connector Protocol) server that sits on top of the Bins API and exposes three tools LLMs can call to look up bin collection information.

Server (Streamable HTTP MCP): https://bins.felixyeung.com/api/mcp

You can connect to the MCP server with the following configuration:

{
  "mcpServers": {
    "bins": {
      "url": "https://bins.felixyeung.com/api/mcp"
    }
  }
}

Overview

The MCP wraps the existing HTTP API (see API Reference) and exposes three tools:

  • search_premises_from_postcode - look up premises by UK postcode (returns a list of premises and their ids).
  • show_premises_jobs_by_id - show scheduled bin collection dates for a specific premises (by premisesId).
  • get_premises_permalink - return a permalink to the public premises page.

These tools return both a human-friendly content (array of text blocks) and structuredContent (JSON-friendly data) suitable for downstream programmatic consumption.

Tools

NameDescriptionParametersSample prompt
search_premises_from_postcodeSearch premises/addresses using a UK postcode. Returns a list of premises (each with id and address) that you can use with the other tools.postcode (string, required) - The UK postcode to search. Example: LS6 2SE.”Find addresses for postcode LS6 2SE”
show_premises_jobs_by_idRetrieve scheduled bin collection dates (jobs) for a premises. Each job contains bin and date. The tool also annotates each job with a status (Expired, Today, Upcoming).premisesId (integer, required) - The id returned by search_premises_from_postcode. Example: 842289.”Show me the next bin collection dates for premises 842289.”
get_premises_permalinkReturn the permanent public link for a premises page. The page shows the full address, a mini calendar, full list of collection dates, and an iCal link.premisesId (integer, required) - The id returned by search_premises_from_postcode. Example: 842289.”Give me the permalink for premises 842289 so I can share it.”

Success & Error behaviour

  • On success each tool returns:

    • content - array of { type: "text", text: "..." } blocks for LLM-friendly output.
    • structuredContent - JSON object/array for programmatic use.

  • On error the MCP returns:

    • isError: true
    • content with a helpful error message, e.g.:
      • "No address matching with postcode LS6 2SE found"
      • "Address not found (bad premisesId of 123456)"

  • Rate-limiting follows the underlying API rules (see API Reference): generally 10 requests / 10s per client IP with short bursts tolerated up to 100 before throttling. When throttled the API responds 429 Too Many Requests with retry-after and x-retry-in headers.

This page was generated by AI
Calendar Subscription