Why this guide exists
More and more mWater users are pointing AI assistants and autonomous agents at their data. They use them to build surveys faster, summarize results, fill in dashboards, or bulk-edit records. That's a good thing, and mWater wants to support it.
But there's are more and less structured ways to connect AI, and here the difference matters.
When you ask an agent to "create a survey" or "build a dashboard" and it has no sanctioned, documented channel to use, it tends to do the most direct thing available. It watches the network traffic your browser sends to mWater, works out the internal API, and starts calling that API directly.
That internal API is the same one mWater's own web and mobile apps use. It was never designed to be a public contract. This is not an issue when using the platform as a human because a lot of the rules that keep your data sane live in the app's screens, not on the server. So when an agent skips the screens, it skips the rules too.
We've already seen what happens:
- A dropdown question ended up with more than 40,000 options when a few dozen were intended. The browser's question editor would never let you build that but a direct API call can. This leads to a massively bloated survey that will not load properly.
- A dashboard got created with no permissions at all. The portal won't let that happen, because it always makes you an admin when you create one. But pasted in as raw design data through the API, the dashboard saved just fine, then went invisible to everyone, including the person who made it.
Neither of these was malicious, and as they happen we can tighten the rules. They're just what happens when a capable agent gets a goal and an unguarded back door. This guide is here to help you, and the agents you direct, use the front door instead for the best, most structured experience that doesn't lead to stuck dashboards or surveys.
These issues share a single root cause: an agent calling the internal API skips the layer where mWater's rules live. That same cause produces a whole family of failures we can predict and get ahead of. The section "The broader risk landscape" maps them out, because the goal here is prevention, not patching one incident at a time.
The one principle
Use mWater's sanctioned AI channel, the MCP server. We recommend you do not let agents reverse-engineer the internal browser API and call it directly.
Everything else in this guide follows from that.
The sanctioned channel: the mWater MCP server
mWater publishes a Model Context Protocol (MCP) server. Think of it as a purpose-built, AI-facing connection that does for agents what the portal does for people: it lets them get real work done while enforcing the guardrails that keep your data trustworthy.
It's the recommended way for any AI tool to read from or write to mWater.
Why it's safe by design
- Permission-aware. The agent sees and touches exactly what you can, with the same row-level and table-level permissions as the web app. No elevation, no back doors.
- Scoped, revocable tokens. Access comes from a token you create (read-only or read-plus-propose), not from your browser session. If a tool misbehaves or a token leaks, you revoke that one token and nothing else.
- Writes are proposals, not commits. An agent can propose data changes, but nothing is written until you review and approve it in the portal. You see every before-and-after value first, and proposals expire on their own after 24 hours.
- Structure is protected. The MCP server can edit row data only. It physically cannot redesign your forms, indicators, dashboards, tables, or columns. The 40k-dropdown and locked-out-dashboard problems simply can't happen through this channel.
- Audited. Every action is logged, so you have a record of what the agent did on your behalf.
- Built-in safety limits. Read queries are capped on rows, time, and response size, so an agent can't accidentally pull or stall your whole database.
What the MCP server lets an agent do
- Explore your data structure: list tables, inspect columns, see what's there.
- Search for forms, indicators, custom tables, and calculated data sources by name.
- Run read-only queries against your data using mWater's query language, always respecting your permissions.
- Propose data changes, meaning add, update, or remove rows, which you then approve in the portal.
- Read the Resource Center, so it can look up mWater help articles and answer "how do I..." questions correctly.
What it deliberately won't do
- It won't change the design of forms, surveys, indicators, dashboards, tables, or columns. Those are structural changes that belong in the portal, made by a person (and assisted by AI if you like, as described below).
- It won't write anything without your approval.
- It won't get around your permissions.
These aren't limitations to work around. They're the whole point.
If you need to change structure (forms, dashboards, indicators)
The MCP server can't redesign forms or dashboards on purpose, and the internal API is not a safe stand-in. So how should AI help with design work?
Let the AI help you inside the portal instead of acting on the API. Have the agent draft the survey logic, suggest question wording, or sketch out a dashboard. Then you build or paste it through the portal's own editors, which check the design as you go. The person stays in the loop exactly where the guardrails live.
If you have a real need for programmatic design changes at scale, like generating many similar forms, get in touch with mWater at info@mwater.co. That's something we'd rather build properly, with validation, than have agents improvise against an internal endpoint.
Guidelines for directing agents
Do:
- Connect agents through the MCP server. Set up a token scoped to what the task needs, read-only if the agent only has to analyze.
- Review every proposed change before you approve it. The proposal screen shows exactly what will change, so treat it like a pull request.
- Prefer references over giant option lists. If a question needs hundreds or thousands of possible answers (facilities, villages, products), that data belongs in a table the question points to, not as inline dropdown options. Ask your agent to use a reference or cascading question, or set one up in the portal.
- Tell the agent what not to do. Many agents will honor an explicit contract if you give them one.
- Start small and verify. Run the agent on a test form or a copy before you turn it loose on production data.
Don't:
- Don't ask an agent to "use the API directly" or "figure out the API from the network tab." That's the path that produced every problem above.
- Don't paste raw design JSON (form designs, dashboard designs) into API calls. The server stores whatever it's given, and the validation that would catch the mistake lives in the editor you skipped.
- Don't share your browser session token with a tool as a way to "give it access." Use a scoped MCP token instead. It's safer, and you can revoke it.
- Don't assume the server will catch a bad design. For structural design today, it mostly won't. When you bypass the portal, you are the validation, so don't bypass it.
Quick reference: common mistakes and the right pattern
- Big inline dropdown with hundreds or thousands of options. Put the options in a table and use a reference or cascading question.
- Object with missing or empty permissions. Create it in the portal, which assigns you as admin. Don't hand-author roles.
- Sharing broadly just to make something visible. Share deliberately in the portal. Never widen access to work around an error.
- Bulk or historical data edits through the API. Use the MCP propose-and-approve flow and review the changes before they land.
- Retrying a create after a timeout. Check whether it already succeeded.
- Writing responses around form validation. Submit through the form or the MCP path so validation and sync are respected.
mWater meets AI where it is headed
Capable AI agents are exposing a problem every data platform shares: agents will use whatever interface they can find, and most platforms' internal APIs were never hardened for that kind of use. At mWater we are prepared for this ahead of time. Hopefully these lessons can help other actors in the sector:
- We built an AI-native front door before it became a crisis. The MCP server gives agents a real, productive way to work with mWater while keeping people in control, with permission-aware access, scoped tokens, and a propose-then-approve workflow for every write.
- We treat agent writes the way good engineering treats code: review before merge. Nothing an agent proposes touches your data until a person approves it, with full visibility into the change.
- We protect structure from improvisation. The design of your forms, indicators, and dashboards, the things that are hard to fix once they're corrupted, can't be altered by an agent through the sanctioned channel at all.
- Our help is machine-readable. The Resource Center is exposed to agents through the same server, so AI assistants can answer mWater questions from our real documentation instead of guessing.
This guide, and the agent contract that sits beside it, are the next step. They make the safe path the obvious path, for people and machines alike.
Getting help