Setup guide · API key

Cursor

Ground your agent's location answers in Hillbase records.

Start with a free Hillbase account. Create an API key in your account and keep it private.

Connect Hillbase

  1. Create a key and set HILLBASE_API_KEY in the environment that launches Cursor, then restart the app so it inherits the variable.
  2. Add the JSON below to ~/.cursor/mcp.json (merge mcpServers if the file already exists). This is a user configuration; keep credentials out of project files.
  3. Open Cursor Settings → Tools & MCP and confirm Hillbase is enabled. In Agent chat, paste the first prompt below and allow the tool call.
Bash · set your Hillbase key
# Paste the key shown once in your Hillbase account.
# Run in a private terminal; keep keys out of source control.
read -r -s -p "Hillbase API key: " HILLBASE_API_KEY; printf '\n'
export HILLBASE_API_KEY
~/.cursor/mcp.json
{
  "mcpServers": {
    "hillbase": {
      "url": "https://api.hillbase.com/mcp",
      "headers": {
        "X-API-Key": "${env:HILLBASE_API_KEY}"
      }
    }
  }
}

Client settings can change. See the Cursor MCP guide for current client requirements.

Ask your first question

First prompt
Use Hillbase address_profile for point latitude 49.1416582, longitude -122.8795092, region BC, locality Surrey. Summarize the school assignments, transit and property context. Report each section's coverage status; do not treat unsupported or no_match as proof that something does not exist.

The fixed excerpt below comes from the same address-profile API used by the MCP tool. Your assistant's wording and current records may differ.

Real captured response · school_assignments section excerpt. Captured values can differ from current data.

{
  "schema_version": "hillbase.v0",
  "quality": {
    "basis": "mixed",
    "effective_date": null,
    "last_checked_at": null,
    "limitations": [
      {
        "code": "absence_not_proof",
        "message": "No matching record does not prove that none exists."
      },
      {
        "code": "assessment_not_market_value",
        "message": "An assessed value is not a sale price or current market value."
      },
      {
        "code": "assignment_not_admission",
        "message": "A school assignment does not guarantee admission."
      }
    ]
  },
  "data": {
    "point": {
      "lat": 49.1416582,
      "lng": -122.8795092
    },
    "sections": {
      "school_assignments": {
        "data": [
          {
            "school": {
              "id": "sch_g2nriqq5vei4",
              "name": "Strawberry Hill Elementary",
              "school_type": "elementary",
              "authority": {
                "id": "aut_3usld4ldzlrt",
                "name": "Surrey",
                "authority_type": "school_district",
                "external_id": "BC36"
              }
            },
            "catchment": {
              "id": "cat_fthhjbggwfj6",
              "level": "elementary",
              "program": "Regular",
              "school_year": "2026-2027",
              "grade_start": null,
              "grade_end": null,
              "boundary_version": "62eb312788d0d5b34c433177cd312678172ddf2a0408677a521aef9b8d9247e2",
              "verification_status": "unverified"
            },
            "match_method": "official_boundary",
            "confidence": "high",
            "source": {
              "id": "ca-bc-surrey-school-catchments",
              "record_id": null,
              "updated_at": null,
              "observed_at": "2026-10-08T23:37:04.966500Z"
            }
          },
          {
            "school": {
              "id": "sch_xw46knkm4azw",
              "name": "Princess Margaret Secondary",
              "school_type": "secondary",
              "authority": {
                "id": "aut_3usld4ldzlrt",
                "name": "Surrey",
                "authority_type": "school_district",
                "external_id": "BC36"
              }
            },
            "catchment": {
              "id": "cat_ttoatnlwnxst",
              "level": "secondary",
              "program": "Regular",
              "school_year": "2026-2027",
              "grade_start": null,
              "grade_end": null,
              "boundary_version": "d43d656d971288cdbb153345c28c4a057d4dbe349cb51a990dc58b676856fdb9",
              "verification_status": "unverified"
            },
            "match_method": "official_boundary",
            "confidence": "high",
            "source": {
              "id": "ca-bc-surrey-school-catchments",
              "record_id": null,
              "updated_at": null,
              "observed_at": "2026-10-08T23:37:04.966500Z"
            }
          }
        ],
        "coverage": {
          "capability": "school_assignments",
          "status": "supported",
          "outcome": "resolved",
          "geography": "point",
          "period": null,
          "message": null
        },
        "quality": {
          "basis": "derived",
          "effective_date": null,
          "last_checked_at": "2026-10-08T23:37:04.966500Z",
          "limitations": [
            {
              "code": "assignment_not_admission",
              "message": "A school assignment does not guarantee admission."
            },
            {
              "code": "boundary_year_specific",
              "message": "Boundaries apply to their stated year and may change."
            }
          ]
        },
        "provenance": [
          {
            "source_id": "ca-bc-surrey-school-catchments",
            "source_updated_at": null,
            "observed_at": null,
            "snapshot": null
          }
        ],
        "warnings": []
      }
    }
  },
  "retrieved_at": "2026-10-12T18:51:41.790023Z"
}

Check the answer

Read each section's coverage.status and coverage.outcome. A partial or unsupported section is not proof that no records exist. If connection returns 401, check the exported key is active and inherited by your client. A 429 response includes a Retry-After header.

Revoke a key in your account and update your local configuration. Connections use your Hillbase plan's credits.

Next: query a CSV, save a Signal or browse the endpoint reference.