An MCP server for local business data your assistant can call

What the Model Context Protocol actually is

MCP describes tools to a language model and carries the calls back and forth: a server publishes tools with typed arguments and a written description, and the client hands that list to the model. The protocol is the least interesting part. What decides whether this works is which tools you connect and how they behave when they refuse.

Servers come in two shapes. A local one runs as a process on your machine, which means a package to install and a version to keep current. A remote one is a URL. Locomint is remote — https://api.locomint.io/mcp, HTTP transport, authenticated with the API key you already use for the REST endpoints. Nothing is installed, and a tool we add appears in your client the next time it connects.

Why an assistant needs live local business data

Ask a model for the opening hours of a dentist in Lisbon and it will answer. The answer comes from training data, which is a snapshot of the web from months or years ago, and opening hours are among the fastest-changing facts a business publishes. Numbers get ported. Businesses move, or close permanently and leave the old listing behind.

The dangerous failure is not the model saying it does not know. It is a plausible phone number, formatted correctly for the country, that belongs to nobody. A refusal gets checked; a well-formed wrong answer gets dialled.

A tool call replaces recall with a lookup, and the record that comes back carries a citation with the place id and the time the data was read, so the answer can be traced afterwards. The longer argument for that design is in the piece on grounding an LLM in local business data; the LLM Grounding API is the same thing without the protocol.

How to add the MCP server to Claude Code

One command. Put the key in an environment variable first so it does not end up in your shell history:

claude mcp add --transport http locomint https://api.locomint.io/mcp \
  --header "Authorization: Bearer $LOCOMINT_KEY"

Any client that takes a JSON config file wants the same three things — transport, URL, header:

{
  "mcpServers": {
    "locomint": {
      "type": "http",
      "url": "https://api.locomint.io/mcp",
      "headers": { "Authorization": "Bearer ${LOCOMINT_API_KEY}" }
    }
  }
}

Restart the client and ask it to list its tools. If the list is empty, the header is the usual cause: an unknown or missing key is a 401, and most clients report that as "server failed to start" rather than as an authentication problem. Free keys start with lm_free_ and paid ones with lm_live_; both work here. You can get one on the signup page without a card.

The nine tools and what each one costs

Every tool is a thin wrapper over the REST endpoint of the same name, so a credit costs the same whether the call came from your code or from a model.

Two of the nine cost nothing, and they are the two an agent should reach for first. count_local answers "how big is this job" for free; account_usage answers "can I afford it". Both are documented in the MCP section of the reference alongside the REST endpoints they call.

Credits are reserved at the worst case before any work happens and settled to the real cost afterwards. A local_search with limit=10 reserves ten and settles at four if four businesses came back. A call that would push you past the monthly quota is refused before the work, not after, so it costs nothing.

Arguments are clamped server-side rather than rejected, which matters when a model guesses. local_search takes limit between 1 and 10 and silently pulls anything larger down to 10, so an agent that asks for 50 businesses gets 10 and is charged for 10, not 50. read_page clamps max_chars into 500–200,000 and accepts markdown or text, falling back to markdown for anything else. verify_emails takes the first 100 addresses and raises invalid_request on an empty list rather than returning an empty result the model might read as "none of these work".

A worked example: three coffee shops and one address that works

A real sequence of calls, in the order an assistant makes them when you ask it to find three well-rated coffee shops in Lisbon and give you an address you can actually write to.

First it checks the size of the problem with count_local(query="coffee shop", location="Lisbon, Portugal"). That is free and comes back with a count plus either exact: true — the first page was not full, so that is the whole answer — or at_least: true, meaning a full page came back and a search will find more.

Then local_search(query="coffee shop", location="Lisbon, Portugal", limit=3, detail=true). With detail set, each record carries all seven days of hours plus the emails, whatsapp and contact_form_url read from the business website. Six credits for three businesses. The response also carries a text field: one line per business with the same facts, which is what the model quotes from.

Finally verify_emails on the addresses that came back, one credit each. Each row returns a status — deliverable, undeliverable, risky for a catch-all domain, disposable, invalid or unknown — with a reason and the individual checks that ran. Ten credits total for the conversation, and the assistant's answer names a business, quotes its hours, and says which mailbox it confirmed.

The order matters. A model that calls place_details on all ten results before filtering spends ten credits to keep three. Count, search small, then fetch details for the ones that survived.

What the model sees when a call fails

Tool errors are returned to the model as sentences, not as exceptions that end the conversation. A wrong place id comes back as not_found with a message, and the model retries with an id it actually has. A spent quota comes back as quota_exceeded with the message, and the model says so instead of filling the gap from memory — which is the whole point of connecting it to real data.

A degraded data path answers 503 with a Retry-After, nothing is charged, and the public status page shows the current canary success rate so you can tell whose problem it is. Rate limits behave the same way: 60 requests a minute on Free and Starter, more on the paid plans, with Retry-After on the 429.

One behaviour to expect from the crawling tools: a site that refuses automated visitors comes back blocked, and a page that renders client-side comes back thin with little content. Neither is retried through another route. Your agent inherits that limit.

Security: what the bearer token can and cannot do

The bearer token is an ordinary Locomint API key, checked against the same key store the REST API uses, so disabling a key stops MCP access at the same moment.

Keep it out of the config file. Clients that support remote servers support environment interpolation, which is why the block above reads ${LOCOMINT_API_KEY} rather than the key. Config files get committed.

The key grants exactly what it grants over HTTP: read access to public business data within your monthly credits. There is nothing destructive to call. The worst outcome of a leaked free key is somebody spending 200 credits, and the worst outcome of a leaked paid key is a month's quota — check GET /v1/usage, which is free, and issue a new key if the numbers look wrong.

Decide one thing before pointing an autonomous agent at this: whether it may spend credits without asking. Most clients let you require approval per tool. Leaving count_local and account_usage automatic while gating local_search and place_details behind a prompt is a sensible default for an agent that runs unattended.

Where to start this week

Add the server, then ask your assistant one question you already know the answer to — a business near you, whose hours you can check by walking past it. Watch which tools it picks and in what order. Most of what you will want to change is prompt-level: telling it to count before searching, to always include the country, and to quote the citation rather than paraphrasing.

After that, decide whether you need the protocol at all. If the calls happen inside your own code rather than inside a conversation, the grounding endpoint is one HTTP GET and gives you the same records and the same text block. MCP earns its place when a model is choosing what to fetch. The MCP server page lists the tools, and pricing shows how far each plan's credits go.

Frequently asked questions

How do I add an MCP server to Claude?

In Claude Code it is one command: claude mcp add --transport http locomint https://api.locomint.io/mcp with an Authorization: Bearer header carrying your Locomint key. In a client that reads a config file, add an mcpServers entry with type http, the same URL and the same header. Restart the client and the nine tools appear in its tool list.

Does the MCP server need its own API key or plan?

No. It uses the same key, the same monthly credits, the same rate limit and the same dashboard as the REST API. A free key works: 200 credits a month, 60 requests a minute, no card. A key you disable stops working over MCP at the same moment it stops working over HTTP.

What happens when the assistant runs out of credits mid-conversation?

The tool returns the error as a sentence, quota_exceeded with the message, rather than an empty result. The model reads it and says the quota is spent instead of inventing a business. Nothing is charged for the refused call, and GET /v1/usage is free, so an agent can check its remaining credits before starting a long job.