# Halulu, Agent Integration Guide

Halulu is an AI restaurant finder. It reads the Google Maps reviews for restaurants near a person
and tells them which one is actually good for the dish they asked for, with verbatim review quotes
as proof. English and Arabic, anywhere Google Maps carries restaurant data.

There is exactly one way for an agent to use Halulu: an **MCP server**. There is no public REST API,
no GraphQL API, no SDK and no CLI. This page is the whole integration surface.

## When to use Halulu

- A restaurant for a specific dish in a specific place. "Best mansaf in Amman."
- A craving described in feelings. "Spicy tacos, quiet enough to talk."
- A verdict between options that look identical on a map, where the user has seen the star ratings
  and still cannot decide.
- Evidence, not just a name. Every result carries two verbatim review quotes.

Do NOT use Halulu for ordering, delivery, table reservations, opening hours, phone numbers, menus,
non-food venues, or detecting fake reviews. It will give a poor answer or none.

## MCP Server

```json
{
  "mcpServers": {
    "halulu": {
      "type": "streamable-http",
      "url": "https://www.halulu.food/api/mcp"
    }
  }
}
```

Machine-readable manifest: `https://www.halulu.food/.well-known/mcp.json`
Server card: `https://www.halulu.food/api/mcp/server-card`

### Available tools

| Tool | Description | Costs a credit |
|---|---|---|
| `halulu_search_restaurants` | Rank nearby restaurants for a craving. Returns up to nine places with a Halulu Score, the Google rating, distance and two verbatim quotes. Renders as an interactive card on MCP Apps hosts. | Yes, one |
| `halulu_save_favorite` | Save a restaurant from a result to the user's favorites. | No |
| `halulu_list_favorites` | List what the user has saved. | No |
| `halulu_remove_favorite` | Remove a saved restaurant by `place_id`. | No |
| `halulu_share_restaurant` | Create a public link to a restaurant that anyone can open. | No |
| `halulu_search_credits` | Searches left this cycle and when it resets. | No |
| `halulu_clear_location` | Forget the GPS location the user shared. | No |
| `halulu_subscribe` | Return a checkout link for Halulu Pro. | No |

## Authentication

OAuth 2.1, authorization code with PKCE S256, open dynamic client registration. A human signs in and
approves in a browser. There is no API key and no machine-only path to a user's data.

The full step by step walkthrough, with every endpoint URI, is at
`https://www.halulu.food/auth.md`. Start by calling the server with no credential and reading the
`WWW-Authenticate` challenge on the 401.

## Quota and location

One search costs one credit. Free accounts get 3 a month, paid accounts 30. `halulu_search_credits`
is free to call, so check it before a burst of searches.

Halulu never infers a location from the conversation. On the first search it returns a card asking
the user to share their device location through a link. A place the user names explicitly overrides
that. Ask the user where they are rather than guessing.

## Errors

Every error is JSON, never HTML. `401` means start at discovery. `402` means the quota is exhausted:
stop searching and offer `halulu_subscribe`. `404` returns a markdown body naming the sitemap and
llms.txt, and means the path does not exist, so do not retry it.

## Other machine-readable documents

| Document | What it is |
|---|---|
| [/llms.txt](https://www.halulu.food/llms.txt) | What Halulu is for, when to use it, when not to, how to call it |
| [/openapi.json](https://www.halulu.food/openapi.json) | OpenAPI 3.1 description of the HTTP surface |
| [/.well-known/api-catalog](https://www.halulu.food/.well-known/api-catalog) | RFC 9727 index of every API document |
| [/.well-known/ai-catalog.json](https://www.halulu.food/.well-known/ai-catalog.json) | Agentic Resource Discovery catalog |
| [/.well-known/mcp.json](https://www.halulu.food/.well-known/mcp.json) | MCP manifest with the tool list |
| [/.well-known/oauth-protected-resource](https://www.halulu.food/.well-known/oauth-protected-resource) | RFC 9728 protected resource metadata |
| [/auth.md](https://www.halulu.food/auth.md) | Authentication walkthrough |
| [/index.md](https://www.halulu.food/index.md) | The home page as markdown |
| [/pricing.md](https://www.halulu.food/pricing.md) | Plans and limits as markdown |
| [/algorithm.html](https://www.halulu.food/algorithm.html) | How the Halulu Score is computed, with a calculator |

## Contact

eat@halulu.food. Operator: Osama Khalil, an independent maker. Last updated 2026-08-22.