# MCP tools

MAIA's MCP connector exposes fourteen tools. With them an MCP client can find a county, start a project, bring in a file, send a request to MAIA's agent, follow the run, answer its questions, and save skills and memory.

Updated: 2026-09-30. Source: https://maia-analytics.com/docs/mcp/tools

## Every tool at a glance

| Tool | What it does | Changes data |
| --- | --- | --- |
| [`find_county`](https://maia-analytics.com/docs/mcp/tools#find-county) | Finds counties you can build projects in, by name | No |
| [`create_project`](https://maia-analytics.com/docs/mcp/tools#create-project) | Creates a project in a county and starts MAIA on a request or a skill | Yes |
| [`get_upload_link`](https://maia-analytics.com/docs/mcp/tools#get-upload-link) | Gets a one-use link to bring a file into a project, or into a new project in a county | Yes |
| [`get_import`](https://maia-analytics.com/docs/mcp/tools#get-import) | Reports an address import: rows matched, rows not matched and why, or why it failed | No |
| [`send_message`](https://maia-analytics.com/docs/mcp/tools#send-message) | Sends another request, or runs a skill, on an existing project | Yes |
| [`get_run`](https://maia-analytics.com/docs/mcp/tools#get-run) | Reports a run: progress, then the answer, a question, or an error | No |
| [`respond`](https://maia-analytics.com/docs/mcp/tools#respond) | Answers the question or approval MAIA is waiting on | Yes |
| [`stop_run`](https://maia-analytics.com/docs/mcp/tools#stop-run) | Stops the current run. MAIA keeps what it finished | Yes |
| [`list_projects`](https://maia-analytics.com/docs/mcp/tools#list-projects) | Lists the projects you can see, most recently updated first | No |
| [`get_project`](https://maia-analytics.com/docs/mcp/tools#get-project) | Describes a project: layers, columns, row counts, and views | No |
| [`maia_guide`](https://maia-analytics.com/docs/mcp/tools#maia-guide) | Returns what MAIA does, requests that work well, and its limits | No |
| [`list_skills`](https://maia-analytics.com/docs/mcp/tools#list-skills) | Lists your skills and your workspace's skills | No |
| [`save_skill`](https://maia-analytics.com/docs/mcp/tools#save-skill) | Saves one of your own skills | Yes |
| [`save_to_maia_memory`](https://maia-analytics.com/docs/mcp/tools#save-to-maia-memory) | Saves a titled note to your MAIA memory | Yes |

Two more tools exist only for the [in-chat project view](https://maia-analytics.com/docs/mcp/project-view). Your client does not call them.

Every tool also accepts `intent`, an optional sentence of up to 500 characters on the goal of the call. MAIA records it with the call for its own logs. It does not change what the tool does. Leave out names, addresses, and anything private.

### `maia_guide`

No parameters beyond `intent`. Returns a short guide written for your client to read before it uses MAIA.

## Starting work

### `find_county`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `query` | string | Yes | County name, optionally with state, such as "Maricopa, AZ" |

Returns each match with its `county_fips` and `name`. Only counties your workspace can use are returned.

```json
{ "county_fips": "04013", "name": "Maricopa County, AZ" }
```

Pass `county_fips` on as a string. As a number it loses its leading zero.

### `create_project`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `county_fips` | string, 5 digits | Yes | The county code from `find_county` |
| `request` | string | Unless `skill` is set | What to build, in plain language |
| `skill` | string | No | The name of a skill from `list_skills` for MAIA to run |
| `request_id` | string, up to 128 characters | No | An id of your choosing. A retry with the same id returns the same project and run |

Returns at once with a run report holding the project id and the run id. Follow the run with `get_run`. The report's fields are on [Runs and approvals](https://maia-analytics.com/docs/mcp/runs-and-approvals).

### `send_message`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `project_id` | string | Yes | The project to work on |
| `message` | string | Unless `skill` is set | The next request |
| `skill` | string | No | The name of a skill to run on this project |

Returns at once with a run report. Use it for questions about the data too. MAIA refuses a new request while a run is in progress on the project, so wait for `complete` first.

## Bringing in a file

The steps, from your side, are on [Upload a file from Claude](https://maia-analytics.com/docs/mcp/upload-a-file).

### `get_upload_link`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `project_id` | string | Unless `county_fips` is set | A project you can edit, to add the file to |
| `county_fips` | string, 5 digits | Unless `project_id` is set | The county code from `find_county`. The upload creates a new project there |
| `layer_name` | string, up to 255 characters | No | The new layer's name. Defaults to the file name. A new project built from addresses names its layer itself |
| `truncate` | boolean | No | `true` imports only the first rows of a file over the row limit. Defaults to `false`. Your client asks you first |

Returns a one-use link and the command that sends the file to it. The link expires after 10 minutes and works only for you. Your client sends the file from its own code environment, not through a tool call. The response to the upload names the project and, for addresses, an `import_id` to follow with `get_import`.

### `get_import`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `import_id` | string | Yes | The `import_id` from the upload's response |
| `wait_seconds` | integer, 0 to 45 | No | How long to wait for the import to finish before answering. Defaults to 30 |

Returns the import's progress, then the rows matched to parcels and the rows not matched, with the reason for each. If the import failed, it says why. Only an address import needs it: a map layer or a table is in the project when the upload returns.

## Following a run

### `get_run`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `project_id` | string | Yes | The project the run belongs to |
| `run_id` | string | No | The run id from `create_project`, `send_message`, or `respond`. Omitted, the project's current or latest run |
| `wait_seconds` | integer, 0 to 45 | No | How long to wait for the run to finish before answering. Defaults to 30. Keep it under your client's own tool timeout |

Returns a run report. Its fields are described in [Runs and approvals](https://maia-analytics.com/docs/mcp/runs-and-approvals).

### `respond`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `project_id` | string | Yes | The project that is waiting |
| `choice` | string | For a question | The id or the label of the option to pick |
| `approve` | boolean | For an approval | `true` lets MAIA run the step. `false` declines it |
| `note` | string, up to 2,000 characters | No | Why you declined. MAIA reads it when `approve` is `false` |

Send `choice` for a question and `approve` for an approval. The report says which kind is pending. A call with the wrong one, or with nothing pending, is refused.

```json
{ "project_id": "3f6c1a2e-0000-0000-0000-000000000000", "choice": "a" }
```

```json
{ "project_id": "3f6c1a2e-0000-0000-0000-000000000000", "approve": false, "note": "Too many rows. Offer a smaller run." }
```

Returns the run report. The run continues.

### `stop_run`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `project_id` | string | Yes | The project whose run to stop |

Returns whether a run was in progress. A stop is not instant. MAIA halts at the next safe point and keeps what it finished. Calling it twice is safe.

## Reading projects

### `list_projects`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `limit` | integer, 1 to 100 | No | How many to return. Defaults to 25 |

Each project comes with its id, name, status, last update, and a link to it in MAIA.

### `get_project`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `project_id` | string | Yes | The project to describe |

Returns the project's layers, each with its kind, row count, and column names. It also returns the views, and whether a run is in progress. It does not return rows. To read them, open the project link.

## Skills and memory

### `list_skills`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `name` | string | No | A skill's name, to get its full instructions |

Without `name`, each skill comes back with its name, description, scope, and kind. The full instructions come back only for a skill asked for by name.

### `save_skill`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `name` | string, up to 120 characters | Yes | The skill's name. Saving the same name replaces your skill |
| `description` | string, up to 400 characters | Yes | What the skill does and when MAIA should use it |
| `instructions` | string, up to 32,000 characters | Yes | The method itself |
| `kind` | `workflow`, `enrichment`, or `agent_column` | No | A new skill defaults to `workflow`. An existing skill keeps its kind |

Saves a personal skill. Workspace skills are edited in MAIA. See [Skills](https://maia-analytics.com/docs/capabilities/skills).

### `save_to_maia_memory`

| Parameter | Type | Required | Meaning |
| --- | --- | --- | --- |
| `title` | string, up to 120 characters | Yes | A short section name. Saving the same title replaces that section |
| `content` | string, up to 8,000 characters | Yes | The note |

MAIA reads this memory in every project. It is part of your personal knowledge. See [Knowledge](https://maia-analytics.com/docs/capabilities/knowledge).

> **Note:** Both save tools tell your client to show you the draft and get your yes first. Read the draft before you agree.

## Limits

- **The connector is turned on per workspace.**
- **One county per project.** `create_project` takes one county code.
- **No tool reads rows directly.** To ask about the data, send the question to MAIA's agent with `send_message`, and open the project link for the full table.