Developer documentation

LocalWebMCP for developers

A conceptual reference for how an MCP server could expose structured local information to AI agents. Nothing here is a live production API — every interface is labeled Concept, Prototype, Planned or Example.

Overview

Concept

LocalWebMCP is proposed as a Model Context Protocol server sitting between AI systems and structured local information. Clients connect once and gain a consistent vocabulary for businesses, places, services, offers, events and geography.

Conceptual client configuration

{
  "mcpServers": {
    "localwebmcp": {
      "url": "https://mcp.localwebmcp.com/v0",
      "transport": "http",
      "headers": { "Authorization": "Bearer <example_token>" }
    }
  }
}

Architecture

Concept

AI AGENT
   ↓  (MCP)
LOCALWEBMCP        access layer
   ↓
THE LOCAL GRAPH    relationships
   ↓
BUSINESSRECORDOS   record management
   ↓
ONE BUSINESS RECORD  identity
   ↓
ENTITIES  businesses · places · people · services · products · events

MCP Tools

Prototype

search_local_entities

Broad entity search across businesses, places, services and local records.

get_business_record

Retrieve the full canonical record for a single business identity.

find_businesses

Filtered business lookup by category, service, geography or attributes.

get_location

Resolve a physical location node and its parent geographic entities.

get_city

City-level entity: identity, geography, categories and child records.

get_county

County-level entity with contained cities and service coverage.

get_state

State-level entity and its counties within the USA namespace.

search_services

Search service entities independent of a single business.

get_business_hours

Structured operating hours, exceptions and holiday schedules.

get_business_offers

Current conceptual offers, promotions and availability windows.

get_reviews

Aggregated review signals attached to a business record.

get_local_information

Non-business local information: civic data, notices, community context.

resolve_service_area

Determine whether a business serves a given place, ZIP or coordinate.

get_entity_relationships

Traverse graph edges from an entity to connected local entities.

Explore interactive request and response payloads in the tool explorer.

Resources

Planned

Conceptual MCP resources

localwebmcp://business/{business_record_id}
localwebmcp://city/{state}/{city}
localwebmcp://county/{state}/{county}
localwebmcp://state/{state}
localwebmcp://service/{service_id}
localwebmcp://graph/{entity_id}/relationships

Example requests and responses

Example

Request

{
  "tool": "search_local_entities",
  "arguments": {
    "query": "plumbers",
    "city": "Duluth",
    "state": "MN",
    "limit": 3
  }
}

Response

{
  "entities": [
    {
      "business_record_id": "BR-MN-DUL-104882",
      "name": "Northshore Pipe & Drain",
      "type": "business",
      "categories": ["plumbing", "drain_cleaning"],
      "city": "Duluth",
      "county": "St. Louis",
      "state": "MN",
      "verification": "example_verified"
    }
  ],
  "note": "Example response. Fictional data."
}

Authentication concept

Concept

Access would be issued per client application with scoped bearer tokens. Read scopes cover discovery and retrieval; action scopes would require explicit business consent recorded on the Business Record.

Authorization: Bearer lwm_example_5f2c...
X-LWM-Client: example-agent/0.1

scopes: entities.read  records.read  graph.read
        offers.read    actions.request (planned)

Permissions concept

Planned

{
  "business_record_id": "BR-MN-DUL-104882",
  "agent_permissions": {
    "read_record": true,
    "read_offers": true,
    "request_quote": "requires_consent",
    "book_appointment": "requires_consent",
    "contact_business": "rate_limited"
  }
}

Rate limits concept

Concept

tier: example_developer
  60 requests / minute
  10,000 requests / day

tier: example_platform
  600 requests / minute
  negotiated daily ceiling

headers:
  X-LWM-RateLimit-Remaining: 58
  X-LWM-RateLimit-Reset: 41

Business Record schema

Example

BusinessRecord {
  business_record_id: string     // canonical identity
  name: string
  address: PostalAddress
  city: string
  county: string
  state: string
  coordinates: { lat: number, lng: number }
  categories: string[]
  services: string[]
  service_areas: string[]
  hours: Hours
  phone: string
  website: string
  verification: "unverified" | "claimed" | "example_verified"
  reviews: { rating: number, count: number }
  offers: Offer[]
  structured_data: Record<string, unknown>
}

Geographic schema

Example

Country { country_id: "USA", states: StateRef[] }
State   { state_id: "ST-MN", name, counties: CountyRef[] }
County  { county_id: "CNTY-MN-STLOUIS", state_id, cities: CityRef[] }
City    { city_id: "CITY-MN-DUL", county_id, state_id }
Location { location_id, city_id, coordinates }

Entity schema

Example

Entity {
  entity_id: string
  type: "business" | "location" | "service" | "product"
      | "person" | "event" | "review" | "offer" | "organization"
  labels: string[]
  attributes: Record<string, unknown>
  edges: Edge[]
}

Edge {
  type: "located_in" | "offers_service" | "in_category"
      | "serves_area" | "operated_by" | "hosts_event"
  target: string
}