MCP Server

Koral provides a Model Context Protocol (MCP) server. MCP-compatible AI clients such as Claude, Cursor or your own agents can use it to search your catalogue by image, refine the results in plain language and read the values your feed contains.

The MCP server uses the same search as the Endpoints, so results match what your widget shows.

Server URL

https://search.koral.nu/mcp

The server uses the Streamable HTTP transport. Every tool call takes the searchId of your feed, which you find in the Koral Dashboard. See Authentication for more about the search id.

Connecting a client

Claude Code

claude mcp add --transport http koral https://search.koral.nu/mcp

Claude Desktop, Cursor and other clients

Add the server to the client’s MCP configuration:

{
  "mcpServers": {
    "koral": {
      "url": "https://search.koral.nu/mcp"
    }
  }
}

Clients that only support local (stdio) servers can connect through mcp-remote:

{
  "mcpServers": {
    "koral": {
      "command": "npx",
      "args": ["mcp-remote", "https://search.koral.nu/mcp"]
    }
  }
}

Tools

search_image

Finds products that look like an image. Send imageData, a productId or both. A text query alone is not enough.

Parameter	Type	Required	Description
searchId	string	Yes	Your feed’s search id
imageData	string	One of imageData or productId	Base64-encoded image
productId	string	One of imageData or productId	Find products similar to this product
query	string	No	Text to combine with the image
limit	integer	No	Number of results (default 10)
filter	object	No	Filter on product fields, e.g. { "gender": "female" }
market	string	No	For multi-country feeds: return this market’s prices and product fields
simplified	boolean	No	Return only product ids and scores

refine_search

Narrows earlier results with a follow-up request in plain language, such as “in brown”, “cheaper” or “a matching bag”.

Parameter	Type	Required	Description
searchId	string	Yes	Your feed’s search id
positiveIds	string[]	Yes	Product ids from the earlier results to refine from
query	string	Yes	The follow-up request
limit	integer	No	Number of results (default 20)
filter	object	No	Filter on product fields
market	string	No	For multi-country feeds: return this market’s prices and product fields

detect_products

Finds the products in an image and returns a bounding box, outline and label for each, plus any gender or age group it detects.

Parameter	Type	Required	Description
searchId	string	Yes	Your feed’s search id
imageData	string	Yes	Base64-encoded image

get_suggestions

Returns suggested follow-up searches for a product, such as matching items or other colours. Each suggestion has a label and a query you can pass to refine_search.

Parameter	Type	Required	Description
searchId	string	Yes	Your feed’s search id
productId	string	Yes	The id of a product from the search results

get_vocabulary

Lists the values that exist in your feed for fields such as color, product_type and gender. Agents use it to build filters that match your data.

Parameter	Type	Required	Description
searchId	string	Yes	Your feed’s search id
fields	string[]	No	Only return these fields

Example

A typical agent flow:

1. detect_products on a photo to find the jacket in it.
2. search_image with the photo to get similar jackets.
3. refine_search with the ids of the best matches and the query “in brown”.
4. get_suggestions on the chosen product to offer “jeans to go with it”.

Errors

If a tool fails, the result is marked as an error and its text explains why, for example Error: Invalid feed ID for an unknown searchId. See Errors for the underlying API errors.