Setup guide · API key

OpenAI Responses API

Call the remote MCP server from your application using the Responses API.

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

Connect Hillbase

Export HILLBASE_API_KEY, OPENAI_API_KEY and OPENAI_MODEL (a model supporting remote MCP). Your model provider key is separate from your Hillbase key.
Install the SDK with python -m pip install -U openai and save the code below as hillbase_agent.py.
Run python hillbase_agent.py. Only address_profile is enabled in this example; the key is passed as a Bearer credential on each request.

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

Bash · install SDK and set provider credentials

python -m pip install -U openai
read -r -s -p "OPENAI API key: " OPENAI_API_KEY; printf '\n'
export OPENAI_API_KEY
read -r -p "MCP-compatible model ID: " OPENAI_MODEL
export OPENAI_MODEL
# Save the Python example below as hillbase_agent.py, then run:
# python hillbase_agent.py

hillbase_agent.py

import os
from openai import OpenAI

response = OpenAI().responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="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.",
    tools=[{
        "type": "mcp",
        "server_label": "hillbase",
        "server_url": "https://api.hillbase.com/mcp",
        "authorization": os.environ["HILLBASE_API_KEY"],
        "allowed_tools": ["address_profile"],
        "require_approval": "never",
    }],
)
print(response.output_text)

Client settings can change. See the Responses API remote 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.