Give an AI agent grounded Mappls tools

Define the user and system contract

An assistant must research solutions and answer place or routing questions with governed Mappls tools instead of invented endpoints or unapproved live-location access. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Choose and isolate the transport

Start with the downloadable Spatial Operations Agent in fixture mode. Use its local stdio client for a same-host server or authenticated Streamable HTTP client for a remote resource. Keep inbound and provider credentials independent; the client accepts an absolute stdio entrypoint or exact HTTPS MCP URL, never a shell string or credential-bearing URL.

const nearbyPlacesTool = {
  name: "mappls_search_nearby",
  description: "Find real places near a validated Mappls Pin or coordinate.",
  inputSchema: {
    type: "object",
    required: ["location", "category"],
    properties: {
      location: { type: "string", description: "Mappls Pin or 'lat,lng'." },
      category: { type: "string" },
      radiusMeters: { type: "integer", minimum: 50, maximum: 10_000 }
    }
  }
};

Prove offline research first

Select solution_research and the offline profile. Negotiate advertised tools, retrieve capability and deterministic industry/platform plans without a provider credential, require explicit catalog provenance, and make unavailable live tools a visible state.

Use the normalized source contract below as the executable boundary. Switch tabs to compare credential-safe languages without changing the operation.

curl --request GET \
  --url 'https://ai.mappls.com/models' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Bind live-read authority

Deploy live-read separately. Validate asymmetric signature, exact issuer and resource audience, subject, client, expiry, and profile scope. Keep provider credentials only in the MCP workload and publish protected-resource metadata without issuing tokens from the MCP service.

Bound every result

Allow-list planned tools, cap arguments, request time, transport buffers, and structured output, reject gateway-token reflection, and require valid provider provenance from live tools.

Separate plan, approval, and execution

Hash the proposed tool plan, require approval for sensitive scopes, expire approval, reject any execution whose plan or arguments changed, and close the client on shutdown.

Ground the answer

Store tool-call evidence without secrets, cite the provider or catalog result used for each claim, and surface uncertainty or unavailable tools instead of fabricating data.

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when fixture, real stdio, and remote http paths preserve one client contract; offline solution research completes without provider credentials; both real transports negotiate the intended read-only profile; wrong-audience, expired, insufficient-scope, hidden-tool, oversized-output, and token-reflection paths fail closed; unapproved plans cannot execute; every location claim has tool provenance; tool and gateway errors redact credentials and response bodies. Capture provider request identity without logging credentials or unnecessary precise location.

Failure modes you must exercise

Definition of done

MCP production checks

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.