MCP
Upload a file from Claude
MAIA's MCP connector takes a file you attach in Claude, or in another MCP client, and brings its rows into a MAIA project. Your client sends the file to MAIA, and MAIA matches the rows to parcels or adds them as a map layer or a table, the same way an upload in the web app does.
What you end with#
You attach a file in the chat and say where its rows go.
You ask
Bring the places in this file into a new MAIA project in San Francisco County.
Your client does the rest. There is no MAIA page to open. When the import finishes, your client reports:
- the link to the project
- how many rows MAIA imported
- how many rows it skipped because they are outside the county
- for addresses, how many rows matched a parcel and how many did not
Before you start#
You need the MAIA connector connected and signed in. See Connect. MAIA needs no other setting.
What else you need depends on your client.
| Client | What to do |
|---|---|
| Claude Code | What to doNothing more |
| Claude on the web and desktop | What to doAllow MAIA's API domain once, as below |
| Other MCP clients | What to doThe client must be able to send a file over HTTPS to api.maia-analytics.com |
Allow MAIA's domain in Claude#
Claude sends the file from its code sandbox. By default, the sandbox reaches only package-manager domains, so Claude cannot reach MAIA until you allow it.
On a Pro or Max plan:
- Open Settings, then Capabilities.
- Under Code execution and file creation, make sure code execution is on, and keep Allow network egress on.
- Under Additional allowed domains, enter
api.maia-analytics.comand choose Add.
Note
On a Claude Team or Enterprise plan, a workspace admin adds api.maia-analytics.com to the organization's allowed domains. Code execution must be on.
If you skip this step, the upload is blocked. Claude tells you which domain to allow and where. Add it, and Claude can try again with the same link.
Bring a file in#
- Attach the file in the chat.
- Say where the rows go: a project you can edit, or a new project in a county you name.
- Wait for the report. Address rows are matched in the background, and your client checks on them until they finish.
A project covers one county. Rows outside that county are skipped, so split a list that spans counties and bring each part into its own project.
What MAIA does with the file#
MAIA picks the route from the file itself, the same way it does for an upload in the web app.
| The file holds | You get |
|---|---|
| Street addresses | You getYour rows matched to parcels |
| Coordinates or shapes | You getA map layer of your own features |
| Anything else | You getA table the agent can read and join |
How MAIA reads a file and matches its addresses is on the File upload page.
Formats and limits#
The formats and the limits are the same as for an upload in the web app: CSV, TSV, Excel (.xlsx), Parquet, GeoJSON, KML, KMZ, GeoPackage, and zipped Shapefile.
| Limit | Value |
|---|---|
| File size | Value25 MB |
| Rows, matched to parcels by address | Value1,000 |
| Rows, as a map layer or a table | Value10,000 |
A file with more rows than the limit does not fail. Your client can ask MAIA to import only the first rows that fit. See File formats and Limits.
How the upload works#
Your client asks MAIA for an upload link, then sends the file to that link from its own code environment. The file does not pass through the chat's tool calls.
- A link works once. Each link imports one file.
- A link expires after 10 minutes.
- A link is yours alone. It works only for you, and only for the project or the county it was made for.
Troubleshooting#
| What you see | Likely cause | What to do |
|---|---|---|
| Claude says the upload was blocked | Likely causeapi.maia-analytics.com is not an allowed domain | What to doAllow MAIA's domain, then ask Claude to try again |
| Claude cannot run code | Likely causeCode execution is off | What to doTurn it on under Settings, then Capabilities |
| Fewer rows than in the file | Likely causeRows outside the project's county were skipped | What to doCheck the skipped count in the report, and bring those rows into a project in their own county |
| Addresses left unmatched | Likely causeMAIA found no single parcel for them | What to doSee How matching works |
| The link has expired | Likely causeMore than 10 minutes passed, or the link was used | What to doAsk your client to start the upload again |
Tools#
Two tools carry an upload. Your client calls them for you.
| Tool | What it does |
|---|---|
[get_upload_link](/docs/mcp/tools#get-upload-link) | What it doesGets a one-use upload link for a project, or for a new project in a county |
[get_import](/docs/mcp/tools#get-import) | What it doesReports an address import: its progress, then the matched and unmatched rows |
Related#
- File upload covers uploads in the web app.
- Runs and approvals covers what to ask MAIA once your rows are in.