Geographic data for AI agents

Account holder agreement

Before protected API or MCP access, the verified account holder must review and expressly accept the current Terms. Agents use that account’s acceptance; they do not need to scroll or submit consent themselves. A material revision can require renewed acceptance.

HTTP 403 with terms_acceptance_required includes an acceptance_url and agreement version. REST errors place these fields in error.details; MCP transport errors place them in detail. Open the URL in a browser, sign in as the holder, and accept before retrying. An unlinked legacy credential returns terms_account_required; an administrator must link its holder without changing its purchased access. Health, public documentation, account recovery and billing cancellation remain available.

Connect to our MCP server

The Streamable HTTP endpoint is https://api.geoamcan.com/mcp. Configure an MCP-capable client with that exact URL and an existing service bearer token authorized for MCP. This page at /mcp/ is the connection guide; the protocol endpoint has no trailing slash.

Request API and MCP access. Access is provisioned through existing service credentials. Keep the token in your client’s secure credential mechanism, never in public source code.

Example: VS Code MCP configuration

Use the following configuration in .vscode/mcp.json. Your client prompts for the credential; the example contains no real token.

{
  "inputs": [
    {
      "id": "geoamcan-token",
      "type": "promptString",
      "description": "GeoAmCan service token",
      "password": true
    }
  ],
  "servers": {
    "geoamcan": {
      "type": "http",
      "url": "https://api.geoamcan.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:geoamcan-token}"
      }
    }
  }
}

Discover, then retrieve

1. Initialize the MCP connection and request tools/list to inspect current input and output schemas.
2. Call list_datasets with an empty arguments object to inspect dataset coverage and readiness.
3. Select a published dataset and use the relevant authorized data tool. Preserve source, release, geography, units and uncertainty from the response.

Do not infer tool availability from a dataset name. The live tool list and the API reference describe the current contract. Browse dataset documentation for examples and limitations.

Consult the Librarian

ask_librarian accepts a natural-language question, an idempotency_key of 16–100 letters, digits, underscores or hyphens, and an optional conversation_id. It returns a durable request ID. Retrieve the result with get_librarian_response and that request_id.

These tools require a separately enabled Librarian account entitlement and a configured account/billing integration. Seeing a tool in discovery does not grant access. Without that entitlement, the Librarian call is rejected. Ordinary authorized MCP dataset tools remain available independently.

One submitted user question counts as one chat; polling does not create another chat. Reuse the idempotency key when retrying the same submission. The structured response includes capability references, publication status, access requirements, documentation links and limitations. The Librarian explains capabilities; separate authorized tools perform data operations.

Authentication and limits

Anonymous protocol requests are rejected. MCP uses the existing service permissions, expiry, rate limits and usage accounting. It does not provide an anonymous alternative to the public Librarian’s guest allowance. A listed tool may reject a call when the credential lacks permission or the requested capability is unavailable.

Reliable evidence for your agent

Use the current catalog JSON for publication status and the OpenAPI contract for REST schemas. Distinguish stored source records from published data, and keep US and Canadian definitions separate. Missing and suppressed observations are not zero.

Guide: ground AI agents in cited public data · Data methodology