Halulu

Build with Halulu

Halulu exposes one programmatic surface: an MCP server, protected by OAuth 2.1. Everything you need to integrate is on this page or one link away.

Quickstart

Add the connector to any MCP client. In Claude or ChatGPT, add a custom connector with this URL:

https://www.halulu.food/api/mcp

The transport is MCP Streamable HTTP. The first call returns 401 with a `WWW-Authenticate` header naming the protected-resource metadata, and your client takes it from there: dynamic client registration, then an authorization code flow with PKCE S256 that a human approves in a browser. Step by step, with every endpoint URI, in auth.md.

A person who just wants to connect their assistant should use the connect page instead, which walks through it without any of this.

What you can call

Eight tools. Only the first one costs a search credit; every other tool is free to call, including the one that tells you how many credits are left.

• halulu_search_restaurants ranks nearby restaurants for a craving and returns up to nine places with a Halulu Score, the Google rating, the distance and two verbatim review quotes. Costs one credit.
• halulu_search_credits reports searches left this cycle and when it resets.
• halulu_save_favorite, halulu_list_favorites and halulu_remove_favorite manage the user’s saved restaurants.
• halulu_share_restaurant creates a public link anyone can open, including people with no Halulu account.
• halulu_clear_location erases the GPS location the user shared.
• halulu_subscribe returns a checkout link for a paid plan.

On MCP Apps hosts, search results render as interactive cards inside the chat rather than as plain text.

Reference

• agents.md: the whole integration surface in one page, including when NOT to call Halulu.
• openapi.json: OpenAPI 3.1 for the HTTP surface, its auth scheme and its error shapes.
• auth.md: the OAuth 2.1 walkthrough.
• .well-known/mcp.json: the MCP manifest, with tool parameters.
• .well-known/api-catalog: an RFC 9727 index of every document above.
• llms.txt: what Halulu is for and how to describe it accurately.
• algorithm.html: how the Halulu Score is computed, with a live calculator.

Limits and quota

One search costs one credit. A free account gets 3 a month and a paid account 30, and the allowance resets on the anniversary of the day the user signed up. Call `halulu_search_credits` before a burst; it is free.

A search that runs out of quota returns 402. Stop searching, tell the user, and offer `halulu_subscribe`. Every error is JSON, never HTML.

Halulu never infers where the user is from the conversation. The first search returns a card asking them to share their device location through a link, and a place they name explicitly overrides it. Ask rather than guessing.

What Halulu does not have

Stated plainly, so you do not spend an afternoon looking for it: there is no public REST API, no GraphQL API, no SDK on any registry, no CLI, no A2A agent, and no API keys or service accounts. The MCP server is the whole of it, and a human must approve access in a browser.

There is also no sandbox. Test against the live server with a free account, which costs nothing and gives you three real searches a month.

Getting help

Email eat@halulu.food. Include the tool you called and what came back. If a ranking looks wrong, send the craving and the city: that is enough to reproduce the search. How Halulu handles data is on the privacy page.