Developers / MCP server

Run your locator by chatting.

The Model Context Protocol is an open standard that lets an AI assistant use your tools. Connect your locator once, then add locations, change how the map looks, and get your embed code without opening the dashboard.

Endpoint: https://app.handledlocal.com/api/mcp
Transport: Streamable HTTP
Auth: Sign in with your account, or an API key

Connect a client

In Claude and ChatGPT you simply sign in: no key to create, nothing to copy. Developer tools such as Claude Code and Cursor take an API key instead.

Claude

Open Settings, then Connectors, then Add custom connector, and paste the endpoint above. Claude sends you to a Handled Locator sign-in page. Log in, approve the connection, and you are back where you started.

The connection covers the one locator on the account you signed in with, and you can disconnect it at any time from the same screen.

ChatGPT

Open Settings, then Apps & Connectors, then Advanced, and turn on Developer mode. Add a connector with the endpoint above. ChatGPT runs the same sign-in and approval flow as Claude.

For key-based clients, generate a key in the dashboard under Data, then Developer tools. A free trial account can do this on day one. Give the key write access if you want the assistant to change anything; a read-only key can look but not touch.

Claude Code

Add the server with your key, then use it from any session in that project.

claude mcp add --transport http locator https://app.handledlocal.com/api/mcp \
  --header "Authorization: Bearer hl_live_your_key"

Cursor, Claude Desktop and other JSON-configured clients

Point the client at the endpoint and send the key as a header.

{
  "mcpServers": {
    "locator": {
      "url": "https://app.handledlocal.com/api/mcp",
      "headers": { "Authorization": "Bearer hl_live_your_key" }
    }
  }
}

What to say

You talk to your assistant in plain words and it picks the right tool. Every prompt below has been run, word for word, against a live locator. Swap in your own names, addresses and colours.

Locations

“What locations do I have in my store locator?”
“Add a new location: Riverside Coffee Uptown, 2800 Routh St, Dallas TX 75201”
“Which of my locations is closest to Fort Worth?”

Tags and buttons

“Add the Flagship tag to my Dallas locations”
“Add a "Book a table" button linking to https://example.com/book on all my Dallas locations, in #C2540E”

How it looks

“What does my locator look like right now?”
“Change the accent colour to a deep green and show me what would change before you apply it”

Going live

“Give me the embed code for my locator”

Tools

Fifteen of them. Your assistant picks the right one from what you ask, so you rarely name them yourself.

Tool	Changes data	What it does
`list_locations`	No	Every location, newest first, searchable by name or address.
`get_location`	No	Full detail for one location, including hours and custom fields.
`create_location`	Yes	Add a location. A plain address is geocoded automatically.
`update_location`	Yes	Change only the fields you send. A new address is re-geocoded.
`delete_location`	Yes	Take a location off the locator. Soft, so it stays recoverable.
`find_nearest_locations`	No	Rank by distance from a point, the way the widget ranks for a visitor.
`list_tags`	No	Your tags, and how many locations carry each one.
`tag_locations`	Yes	Tag many locations at once. Creates the tag if it is new.
`set_custom_field`	Yes	Put a booking button, link or fact on many locations at once.
`describe_configuration`	No	Every setting, brand token, layout and label, with its current value.
`propose_configuration`	Yes	Prepare a change and return the exact differences. Applies nothing.
`apply_configuration`	Yes	Make a prepared change live on your website.
`list_configuration_versions`	No	Configuration history, for picking a version to restore.
`rollback_configuration`	Yes	Restore an earlier version by appending a new one.
`get_embed_code`	No	The script tag for your website, and your public site id.

Changes to your live locator take two steps

Restyling your locator changes a page that is live on your website, so an assistant cannot do it in one move. It prepares the change and shows you exactly what would differ, and nothing goes live until you agree.

1. It reads the real options
Every setting, brand token, layout and piece of wording, with its current value. An invented setting is refused rather than quietly ignored.
2. It proposes, and you see the differences
A before and after list, in plain words. Nothing has changed on your site at this point.
3. You apply it, and it stays undoable
Every version is kept, so you can restore an earlier one at any time. If someone edited the locator in the dashboard meanwhile, the proposal is refused rather than overwriting their work.

Deleting a location works the same way: it comes off the locator but stays recoverable from the dashboard.

Access and limits

A connection reaches one locator: the account the key belongs to, and nothing else.
A read-only key is refused at the door for anything that writes, before a single row is touched.
Keys are rate limited, at 120 reads and 30 writes a minute, so a stuck assistant cannot hammer your locator.
Adding locations counts against your plan’s allowance, exactly as it does in the dashboard.
Revoke a key in the dashboard and every client using it stops working immediately.

Treat a write key like an admin login. Only connect clients you trust, and revoke it if a device is ever lost.

Disconnecting

Remove the connector from your client’s settings, or revoke the key in the dashboard. Either way your data stays put: disconnecting removes access, nothing else. Locations, tags and configuration are all still there when you reconnect.

Included on every plan, from the free trial

Start a trial, connect your assistant, and build a real locator by describing it. No code. When the trial ends you pick a plan to keep it running, and everything you built is already there.

The REST location API uses the same key and remains a Pro and Business feature.

Start a free trial See pricing