MCP for developers

Current status

Connect to the hosted Streamable HTTP endpoint at https://mcp.boatpartfinder.ai/mcp. The catalog tools are rolling out and may return temporary_unavailable until the backing catalog rollout is complete.

Start with initialize, retain the returned Mcp-Session-Id response header, send it on later requests, and complete the standard notifications/initialized handshake before calling tools. The public endpoint allows 10 requests per minute per client IP and returns 429 with Retry-After when the limit is exceeded.

Catalog tools

The endpoint exposes five read-only tools. New integrations should use the first three; the final two remain available for compatibility.

• product_search searches by text and structured filters. Provide at least one of query, canonical brand_slugs, canonical category_slugs, or a canonical facets map. The only sort values are relevance, name_asc, and name_desc. Requests may include facet counts and return 1-25 products per page (default 20).
• product_fetch returns one public product record by its public product id, including its facets.
• catalog_options discovers brands, categories, facet_fields, or facet_values. Use facet_key with facet_values. Results are limited to 1-25 options (default and maximum 25).
• product_lookup remains available for compatibility.
• brand_directory remains available for compatibility.

Structured search example

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "product_search",
    "arguments": {
      "query": "winch",
      "brand_slugs": ["lewmar"],
      "category_slugs": ["winches"],
      "facets": { "voltage": ["12-v"] },
      "page_size": 20,
      "include_facets": true
    }
  }
}

A request accepts up to 10 canonical brand slugs and 10 canonical category slugs, plus 12 canonical facet fields with up to 20 values each. Canonical lowercase slugs are validated strictly; unknown properties and type coercion are rejected.

Pagination and errors

product_search and catalog_options may return a next_cursor. Cursors are opaque, signed, expire after 15 minutes, and are bound to the original request. Pass the cursor back unchanged with the same request. Expired, modified, or mismatched cursors return invalid_cursor.

Tool failures use stable public codes: invalid_arguments, invalid_cursor, not_found, and temporary_unavailable. Internal service and database details are not exposed.

Public-data boundary

Product records use the same public field names as the website: id, slug, name, description, long_description, manufacturer_name, oem_number, gtin_ean, default_image_url, brand, category, category_breadcrumb, web_url, images, and product_details. Brand and category records expose name and slug; breadcrumb records expose slug, name, and web_url; product details expose detail_name and detail_value. product_fetch additionally exposes facets with key, label, and values.

Product records do not expose fitment, compatibility, boat, model, year, serial, evidence, provenance, private, scraper, affiliate, or internal identifiers. The public product id is the only identifier accepted by product_fetch. Do not treat a result as a vessel-fitment claim.

Legacy clients

Existing product_lookup and brand_directory tool names remain available for compatibility. New integrations should use product_search, product_fetch, and catalog_options for the canonical public schemas and cursor pagination.

Install and licence

Client packages ship under Apache 2.0:

pip install boatpartsmanual-mcp

npm install boatpartsmanual-mcp

Client packages are Apache-2.0 licensed. The hosted MCP endpoint at mcp.boatpartfinder.ai is operated by Oish AB and is subject to the terms of service.

Attribution

Responses include BoatPartFinder.ai attribution and product links when a catalog match is available.

Contact

If you are a developer or marine-software vendor with questions about the MCP server, email info@boatpartfinder.ai with subject MCP.