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.

A complete locator built in Claude, start to finish. Watch on YouTubeRecorded from the product

ChatGPT

Handled Locator is published in ChatGPT’s plugin directory. Open the Handled Locator plugin, select Install plugin, then sign in and approve, the same flow as Claude. No developer mode and no endpoint to paste.

The same tools, driven from ChatGPT. Watch on YouTubeRecorded from the product

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”
“Put my flavour tags in a "Flavour" filter group, each with a leaf icon and its own colour”
“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

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

list_locationsRead-only

Every location, newest first, searchable by name or address.

get_locationRead-only

Full detail for one location, including hours and custom fields.

create_locationWrites

Add a location. A plain address is geocoded automatically.

Undo: Delete it. The location id is not reused, and anything already pointing at it (a tag, a territory) is deleted with it.

update_locationWrites

Change only the fields you send, on one location or a batch. A new address is re-geocoded.

Undo: Send the old values back, with one exception: changing the address re-geocodes it, and the coordinates it replaced are not kept anywhere to restore.

delete_locationWrites

Take one location or a batch off the locator. Soft, so they stay recoverable.

Undo: Soft delete, so the row and its analytics history survive and support can restore it. It leaves the public locator immediately.

find_nearest_locationsRead-only

Rank by distance from a point, the way the widget ranks for a visitor.

list_tagsRead-only

Your tags, and how many locations carry each one.

tag_locationsWrites

Tag many locations at once. Creates the tag if it is new.

Undo: Call it again with action=remove. Creating a tag that did not exist leaves the tag behind; remove it in the dashboard.

set_tag_styleWrites

Group a tag, colour it, or give it an icon: flat tags become labelled filters.

Undo: Call it again with the previous group, colour and icon. The old values are not stored, so read them with list_tags first if they matter.

set_custom_fieldWrites

Put a booking button, link or fact on many locations at once.

Undo: Call it again with the previous value, or an empty one to clear the field.

describe_configurationRead-only

Every setting, brand token, layout and label, with its current value.

propose_configurationWrites

Prepare a change and return the exact differences. Applies nothing.

Undo: Nothing to undo: a proposal is inert until applied, and is refused outright if the locator moved on in the meantime.

apply_configurationWrites

Make a prepared change live on your website.

Undo: Fully reversible. Every version is kept and rollback_configuration returns to any of them. This is the only tool here with a version history.

list_configuration_versionsRead-only

Configuration history, for picking a version to restore.

rollback_configurationWrites

Restore an earlier version by appending a new one.

Undo: Itself a new version, so rolling back a rollback is another rollback.

list_spotlight_rulesRead-only

Every Spotlight rule in the order it applies, with ids.

create_spotlight_ruleWrites

A banner, featured or exclusive locations, by where and when a visitor searches.

Undo: Delete the rule and it stops applying at once. A banner a visitor has ALREADY been shown cannot be unshown.

update_spotlight_ruleWrites

Replace a rule's trigger, action and dates.

Undo: Update it again with the old values. There is no version history for rules, and a banner a visitor has already been shown cannot be unshown.

set_spotlight_rule_enabledWrites

Switch a rule on or off without deleting it.

Undo: Switch it back. The rule itself is untouched, only whether it applies.

delete_spotlight_ruleWrites

Remove a rule; it stops applying at once.

Undo: None: recreate it by hand. There is no version history for rules, and what visitors were already shown cannot be unshown.

list_territoriesRead-only

Every dealer territory with owner, rank and rules, plus the mode and published version.

explain_territory_ownerRead-only

Which dealer owns a point, and why, from the published territories.

create_territoryWrites

An empty territory owned by one location.

Undo: Delete it. It covers nothing and reaches no visitor until postcodes are added and territories are published.

add_territory_postcodesWrites

Grant or carve out postcodes for a territory.

Undo: Not live until published. Before that, delete and recreate the territory; there is no per-postcode undo or history.

delete_territoryWrites

Remove a territory and its rules.

Undo: None: recreate it. Visitors keep the published version until you publish again, so nothing changes for them until then.

set_territory_modeWrites

Off, preferred, exclusive or fallback: how territories shape results.

Undo: Set the previous mode again. It applies to the live locator straight away.

publish_territoriesWrites

Make the current territories live.

Undo: Edit and publish again. Publishing writes a new version and only makes it live once every file is written, so a failed publish leaves the previous one serving. There is no version history for the rules themselves.

get_embed_codeRead-only

The script tag for your website, optionally locked to some tags.

Tool	Changes data	What it does	Undoing it
`list_locations`	No	Every location, newest first, searchable by name or address.	Nothing to undo.
`get_location`	No	Full detail for one location, including hours and custom fields.	Nothing to undo.
`create_location`	Yes	Add a location. A plain address is geocoded automatically.	Delete it. The location id is not reused, and anything already pointing at it (a tag, a territory) is deleted with it.
`update_location`	Yes	Change only the fields you send, on one location or a batch. A new address is re-geocoded.	Send the old values back, with one exception: changing the address re-geocodes it, and the coordinates it replaced are not kept anywhere to restore.
`delete_location`	Yes	Take one location or a batch off the locator. Soft, so they stay recoverable.	Soft delete, so the row and its analytics history survive and support can restore it. It leaves the public locator immediately.
`find_nearest_locations`	No	Rank by distance from a point, the way the widget ranks for a visitor.	Nothing to undo.
`list_tags`	No	Your tags, and how many locations carry each one.	Nothing to undo.
`tag_locations`	Yes	Tag many locations at once. Creates the tag if it is new.	Call it again with action=remove. Creating a tag that did not exist leaves the tag behind; remove it in the dashboard.
`set_tag_style`	Yes	Group a tag, colour it, or give it an icon: flat tags become labelled filters.	Call it again with the previous group, colour and icon. The old values are not stored, so read them with list_tags first if they matter.
`set_custom_field`	Yes	Put a booking button, link or fact on many locations at once.	Call it again with the previous value, or an empty one to clear the field.
`describe_configuration`	No	Every setting, brand token, layout and label, with its current value.	Nothing to undo.
`propose_configuration`	Yes	Prepare a change and return the exact differences. Applies nothing.	Nothing to undo: a proposal is inert until applied, and is refused outright if the locator moved on in the meantime.
`apply_configuration`	Yes	Make a prepared change live on your website.	Fully reversible. Every version is kept and rollback_configuration returns to any of them. This is the only tool here with a version history.
`list_configuration_versions`	No	Configuration history, for picking a version to restore.	Nothing to undo.
`rollback_configuration`	Yes	Restore an earlier version by appending a new one.	Itself a new version, so rolling back a rollback is another rollback.
`list_spotlight_rules`	No	Every Spotlight rule in the order it applies, with ids.	Nothing to undo.
`create_spotlight_rule`	Yes	A banner, featured or exclusive locations, by where and when a visitor searches.	Delete the rule and it stops applying at once. A banner a visitor has ALREADY been shown cannot be unshown.
`update_spotlight_rule`	Yes	Replace a rule's trigger, action and dates.	Update it again with the old values. There is no version history for rules, and a banner a visitor has already been shown cannot be unshown.
`set_spotlight_rule_enabled`	Yes	Switch a rule on or off without deleting it.	Switch it back. The rule itself is untouched, only whether it applies.
`delete_spotlight_rule`	Yes	Remove a rule; it stops applying at once.	None: recreate it by hand. There is no version history for rules, and what visitors were already shown cannot be unshown.
`list_territories`	No	Every dealer territory with owner, rank and rules, plus the mode and published version.	Nothing to undo.
`explain_territory_owner`	No	Which dealer owns a point, and why, from the published territories.	Nothing to undo.
`create_territory`	Yes	An empty territory owned by one location.	Delete it. It covers nothing and reaches no visitor until postcodes are added and territories are published.
`add_territory_postcodes`	Yes	Grant or carve out postcodes for a territory.	Not live until published. Before that, delete and recreate the territory; there is no per-postcode undo or history.
`delete_territory`	Yes	Remove a territory and its rules.	None: recreate it. Visitors keep the published version until you publish again, so nothing changes for them until then.
`set_territory_mode`	Yes	Off, preferred, exclusive or fallback: how territories shape results.	Set the previous mode again. It applies to the live locator straight away.
`publish_territories`	Yes	Make the current territories live.	Edit and publish again. Publishing writes a new version and only makes it live once every file is written, so a failed publish leaves the previous one serving. There is no version history for the rules themselves.
`get_embed_code`	No	The script tag for your website, optionally locked to some tags.	Nothing to undo.

Things worth knowing before they cost you an hour

Each of these is a trap somebody actually hit, not one we imagined.

A tool that looks broken is usually an approval that was never given: Several read-only tools returning "No approval received" is not an authentication problem and not an outage. It is the client asking you to approve each tool the first time it runs and not getting an answer. Approve them, or remove and re-add the connection.
Your client caches the tool list: A tool added after you connected will not appear, and the assistant will tell you the capability does not exist rather than that it cannot see it. Remove and re-add the connection after any release before concluding something is missing.
Hours are one range per day, not a list: Each weekday maps to a single {open, close} or null for closed, keyed by ISO weekday with 1 as Monday. A list is rejected. `hours` replaces the whole week and clears any day you leave out; `hoursPatch` changes only the days you name, which is what you want for editing.
Publishing is a separate act from editing: Territory rules and Spotlight rules do nothing for a visitor until they are published. A locator that behaves as if your change never happened has usually not been published rather than failed to save.
A service radius is not a territory: A radius says how far a location travels and affects who it can reach. A territory decides who OWNS an address and routes the enquiry. Setting one does not set the other, and a locator can use either, both or neither.
Ids come back in the reply, and are worth keeping: Creating a location or a territory returns its id in the response. Keep it rather than searching by name afterwards: names are not unique, and two locations called Downtown are a coin flip.

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 free trial See pricing