How to connect MAIA MCP with Codex

Find US counties by name, and whether you can build MAIA projects in them, plus cities and towns of that name with their counties: the lookup before create_project for US places.

Resolve US cities, neighborhoods, ZIP codes, metros or regions to the counties a project covers, with the web app's place search; it does not search for businesses. Returns plan counties separately from unavailable counties, unmatched places, county and outline limits, and a question when a name needs the user's choice. Creates nothing. Pass the names as a list to create_project's places for city and neighborhood outlines when available (a notice reports whole-county fallback), or its county codes for whole counties.

List MAIA projects you can see, most recently updated first.

Describe a project: its layers, their columns and row counts, its views and, for its owner, its sharing.

The relations and columns query_project can read in one project, with a handbook on how to query them. Call once per conversation before query_project.

Run one SELECT over a project's own layers and return its rows; it changes no data. A statement over a layer that may hold parcel data spends the workspace's parcel export budget. Call project_schema first: it lists the relations you can name and how to query them. Returns at most 1000 rows and 512 KiB whatever LIMIT you write: total_rows is how many rows the statement returned and truncated says whether the caps cut some, so aggregate in SQL rather than paging rows out. Shared county tables are not reachable here; MAIA's own county records reach you only as the own-data columns and __sales relations project_schema lists.

Report a MAIA run: progress while running, then MAIA's answer, a question, work stopped at the time limit (incomplete), an error, or cancellation. steps lists all started tool calls in order, including repeated labels; steps_started is its length, or null when progress is unavailable. After stop_run, pass its run_id: running means the run has not finished stopping yet. A final stopped status confirms it stopped.

Report a MAIA run's progress to the in-chat view.

Whether a MAIA run is active on a project, without reading its chat.

Use MAIA for questions about places in the United States: which places or properties match criteria, who owns them, what is near them, who lives and works around them, how many there are in an area, or a list of them, from parcels to bike shops, with contacts or other details MAIA researches for each row, such as which ones do repairs. It is not for a business's hours, phone number or directions. Creates a MAIA project and starts MAIA on the request or skill. Read maia_guide first unless you already read it in this conversation. The project starts private unless workspace_access says otherwise; a public link comes later, with set_project_sharing and share_project_publicly. A county_fips marked can_be_county_of_choice is added to the workspace for good, as its one free county outside the plan; pick one only when the user named it. When the plan cannot take a county, or MAIA has no data for it, not_created says why in place of a project; tell the user. Returns at once; follow with get_run.

Ask MAIA a follow-up question or for more work on an existing project, or run a skill on it. Cancels any pending question or approval, so it also answers a question in your own words when none of its options fits; to pick an option or decide an approval, use respond or approve_step instead. Returns at once; follow with get_run.

Answer MAIA's question, or decline its approval (status "needs_input" from get_run). To approve, use approve_step. A question takes one of its options; when no option fits, answer in your own words with send_message instead.

Let MAIA run the step it asked approval for. Call only after the user has read the summary and said yes.

Request a stop of MAIA's current run. MAIA keeps what it finished so far. This acknowledges the request, not completion. Follow the returned run_id with get_run until it is no longer running.

Change who can open a project, and return its sharing. Only the project's owner can.

Turn on a public link that anyone can open, inside or outside the user's organization. Call only after the user read the summary and said yes.

Get a one-use link to import a CSV, Excel, GeoJSON or other data file into MAIA. Post the file to it with the returned curl command; the response names the project and, for addresses, an import to follow with get_import.

Import rows you can read, such as a file the user attached, into MAIA. Choose whether to match addresses using match_addresses; MAIA proposes property columns or asks for a confirmed address_mapping. For a file too large to pass here, use get_upload_link.

Report an address import's progress: rows matched to parcels or places, rows not matched and why, or why it failed. A failed import with no failure_reason committed no rows; unmatched_by_reason explains why.

Search MAIA's published docs and data catalog for MAIA's capabilities, the data it has and where, setup, pricing and integrations. Returns up to five matching sections with page URLs and current workspace availability, never the whole docs set. Cite the sources and respect availability restrictions.

What MAIA does, requests that work well, how runs, usage and approvals work, and its limits.

List the MAIA skills you and your workspace have — reusable workflows MAIA can run.

Save one of your MAIA skills, replacing yours with the same name. Show the user the draft and get their yes first.

Save a note to your MAIA memory, which MAIA reads in every project, replacing the section with the same title. Show the user the note and get their yes first.

The project's layers, a page of rows as its default view shows them, and their shapes, for the in-chat view.