# MCP server

Connect Claude and other Model Context Protocol clients to LookAlike, and use the tools, resources, prompts, and map links.

The LookAlike MCP server uses the Streamable HTTP transport at `https://app.lookalikeiq.com/mcp`. A client connects in one of two ways:

-   **Sign in (OAuth).** The client opens a LookAlike sign-in page. You approve the app, and the client receives its own token.
-   **API token.** You create a token under **Account > API tokens** and paste it into the client configuration.

## Connect a client

### Claude apps (web and desktop)

1.  Open **Settings > Connectors** and add a custom connector.
2.  Enter the URL `https://app.lookalikeiq.com/mcp`.
3.  Select **Connect**. Sign in to LookAlike if asked.
4.  Read the consent page and select **Allow access**.

The consent page names the app and the address it returns to. Approve only apps that you started the connection from. To remove an app, open **Account > Connected apps** and select **Disconnect**.

### Claude Code

Run `claude mcp add --transport http lookalike https://app.lookalikeiq.com/mcp`, then run `/mcp` in Claude Code to sign in. To use an API token instead:

```
claude mcp add --transport http lookalike https://app.lookalikeiq.com/mcp \  --header "Authorization: Bearer lk_your_token"
```

### Clients with HTTP and header support

```
{  "mcpServers": {    "lookalike": {      "type": "http",      "url": "https://app.lookalikeiq.com/mcp",      "headers": { "Authorization": "Bearer lk_your_token" }    }  }}
```

### Clients that support only stdio

Download the CLI. Its `mcp` command forwards stdio messages to the remote server.

```
curl -fsSLo ~/bin/lookalike.mjs https://app.lookalikeiq.com/cli/lookalike.mjs
```

```
{  "mcpServers": {    "lookalike": {      "command": "node",      "args": ["/Users/you/bin/lookalike.mjs", "mcp"],      "env": { "LOOKALIKE_API_TOKEN": "lk_your_token" }    }  }}
```

Signed-in connections use OAuth 2.1 with PKCE and dynamic client registration. Access tokens last one hour. Refresh tokens last 30 days and change on each use. Discovery documents are at `/.well-known/oauth-protected-resource/mcp` and `/.well-known/oauth-authorization-server`.

## Tools

Tool

Required input

Notes

`list_brands`

none

Filter with `query` or `category`.

`get_brand`

`brand`

Typical store tract with a 10th to 90th percentile range, and coherence.

`find_candidates`

`brand` or `stores`

Area filters, `min_similarity`, `include_occupied`, `min_km_from_own_store`, `exclude_competitor_within_6km`, `competitors`, `competitor_categories`, `limit`, `detail`, and `shortlist_top`. `limit` goes up to 25 with `detail: "standard"` and up to 100 with `detail: "brief"`.

`rank_markets`

`brand` or `stores`

`metric` is `opportunity`, `fit`, or `headroom`. `state`, `exclude_states`, and `min_market_tracts` filter metros.

`evaluate_site`

`brand` or `stores`, plus `address` or `lat` and `lon`

`address` takes a street address, a ZIP code, or a city and state. Returns a 3, 5, and 10 km `trade_area`.

`describe_tracts`

`geoids` (1 to 10), plus `brand` or `stores`

All features with national percentiles and the brand’s typical range.

`compare_brands`

`brand_a`, `brand_b`

Correlation, shared tracts, and tracts that lean to each brand. Accepts area filters.

`map_preview`

`brand` or `stores`

A PNG image of similarity. Focus it with area filters. `tracts` highlights up to 25 tracts, numbered in order.

`search_metros`

`query`

Returns CBSA codes. Accepts aliases such as Bay Area. Pass `brand` for map links.

`get_method`

none

Themes, feature keys, thresholds, coverage, sources, caveats, and a glossary.

`make_map_link`

`brand`

Builds a link without an analysis.

`save_view`

`brand` or `stores`

Stores the view on the server and returns a short link. Saving the same view again returns the same link.

`list_views`

none

Saved views from you and your organization, newest first.

`rename_view`, `delete_view`

`view_id`

Work only on views you created.

`get_account`

none

Account, active release, and this hour’s usage.

Every analysis tool also accepts `theme_weights` and `feature_weights`. The input schema lists the valid theme keys, and the `feature_weights` description lists the feature keys.

Rankings leave out special-use tracts by default. These are Census special land-use or water tracts and tracts with fewer than 500 residents, such as airports, parks, military bases, and prisons. Set `include_special_use` to `true` to keep them. Every tract result reports `special_use_tract`.

Tool results arrive as JSON text and as `structuredContent`. Every tool publishes an `outputSchema` with a description of each field. `map_preview` also returns an image content block. Input mistakes return a tool error that names each invalid field and the valid choices, so the model can correct the call. The tool annotations mark which tools save views, and `delete_view` is marked destructive.

## Resources and prompts

Resource

Content

`lookalike://glossary`

The meaning of every result field, as Markdown.

`lookalike://method`

The model, themes, thresholds, coverage, sources, and caveats for the active release.

`lookalike://brands`

Every curated brand with store counts and coherence.

Prompt

Arguments

Workflow

`expansion_shortlist`

`brand`, optional `area` and `count`

Finds, explains, and saves a shortlist.

`site_check`

`brand`, `location`

Evaluates one location with its trade area.

`compare_brands`

`brand_a`, `brand_b`, optional `area`

Explains what separates two footprints.

## Example conversation

A user asks: “Where should Trader Joe’s look next in Colorado?”

1.  The agent calls `find_candidates` with `brand: "Trader Joe's"`, `state: "CO"`, `limit: 5`, and `shortlist_top: 5`.
2.  The agent lists each tract by place, such as Lone Tree, with its reasons, gaps, and nearby chains.
3.  The agent repeats the `interpretation` sentence and gives the user the `shortlist_view` link.

Canonical URL: https://docs.lookalikeiq.com/agents/mcp/
