AI agents are becoming genuinely useful collaborators for technical teams. Tools like Codex, Claude Code, and other agentic development environments can read documentation, inspect files, write code, and work through multi-step tasks. But there is still a practical gap between what an AI agent can reason about and what it can safely do inside the specialised systems that survey teams use every day.
Most serious applications already have APIs, and APIs are the standard programmatic way for software to interact with other software. But raw API access is not automatically a good interface for an AI agent. An API may expose hundreds of operations without explaining which ones are safe, which ones mutate live data, which identifiers are required, which workflow step should happen first, or how a response should be interpreted in the context of a real project.
That matters because AI agents do not just run one pre-written request. They explore, chain actions together, recover from errors, and make decisions about what to try next. If the only bridge into a system is raw API access, the agent needs to infer too much: the security model, the operational meaning of each endpoint, the difference between a harmless read and a live fieldwork action, and the practical workflow around the call. For sensitive systems like Survey Solutions Headquarters, that is not enough. The agent needs a narrower, safer, more meaningful layer between itself and the application.
That is the role of a Model Context Protocol server.
What Is An MCP Server?
The Model Context Protocol, usually shortened to MCP, is a standard way for AI applications to connect to external tools and data sources. An MCP server acts as a bridge between an AI agent and another system.
Instead of asking an agent to guess how to call an API, parse a response, store credentials, or decide which action is safe, the MCP server exposes a clear set of tools. The agent can ask for available tools, see their schemas, call them with structured inputs, and receive structured outputs. The server handles the messy integration details: authentication, API quirks, file handling, pagination, local configuration, permission checks, and safe error messages.
For users, the value is simple: the AI agent becomes more useful because it can work directly with the systems that matter, but in a controlled way. It can inspect a Survey Solutions server, list questionnaires, review assignments, start an export, download the export, summarize its structure, or help prepare a census style workflow without asking the user to manually copy information between windows.
Why Survey Solutions Needed Its Own MCP Server
Survey Solutions already has API access, and that is important. But an API is mainly a technical interface for software. It does not automatically make the system easy, safe, or intuitive for an AI agent to use.
The first issue is setup. A user should not have to piece together API documentation, credentials, local scripts, endpoint names, output folders, and client-specific configuration before an agent can do something useful. A dedicated MCP server gives Codex, Claude Desktop, and other MCP-capable tools a consistent way to connect to Survey Solutions. It can handle the practical integration work once, then expose simple, named tools that match the jobs users are actually trying to do.
The second issue is security. Survey Solutions contains live fieldwork data and operational controls. Some actions are harmless, such as listing questionnaires or checking assignment status. Others can affect interviews, users, workspaces, exports, or approvals. The MCP server lets those different levels of access be separated in plain terms: read-only access for inspection and reporting, fieldwork access for operational changes, administrative access for setup tasks, and tightly controlled raw API access for advanced cases. That makes it easier to give an agent useful access without giving it more power than it needs.
The third issue is experience. Survey Solutions is not just a database with endpoints. It is a fieldwork management system with roles, teams, assignments, interview states, exports, approvals, and review practices. An MCP server can carry some of that practical knowledge. Instead of leaving the agent to infer how a survey manager or data manager would work, the server can guide it through workflows that reflect real Survey Solutions operations.
It is also important to be clear about the purpose of this MCP server. It is for AI agents to interact with the Survey Solutions Headquarters tool: fieldwork setup, operational monitoring, exports, review workflows, and controlled administrative tasks. It is not mainly for coding questionnaires in Designer. We already have a separate Survey Solutions AI chatbot for that purpose, focused on questionnaire logic, validation expressions, and platform-specific programming guidance: https://surveysolutions.impactengines.ai/.
That structure matters. The aim was not just to wrap the API. It was to create a practical working layer for AI agents that reflects how Survey Solutions is used in real survey operations, with setup, security, and workflow guidance built in from the start.
Expert Workflows Matter
One of the most important lessons from this build is that expert users can add value in ways that are not obvious from public API documentation.
An LLM may know what Survey Solutions is. It may be able to read an API page and generate a request. But that is different from understanding a fieldwork workflow.
Take project setup. A generic API wrapper might expose separate operations for users, teams, questionnaires, assignments, and settings. But an experienced Survey Solutions user knows that preparing a questionnaire for fieldwork is a sequence of decisions. Enumerator or interviewer accounts need to exist. They need to sit in teams, with a supervisor responsible for each team. Assignments need to be created either case by case for a sample, or as universal unlimited assignments for census style workflows. The agent should not treat those as isolated calls. It should understand the overall setup pattern, help the user review the plan, and only then apply changes when the user confirms them.
Exports are another simple example. Getting survey data out of Headquarters is not usually a single download link. The export has to be requested, the export job needs to be monitored until it finishes, and only then can the file be downloaded and inspected. The MCP server can package that operational knowledge into a smoother workflow: start the export, poll for completion, download the zip, identify what kind of export it is, and help the user understand what files or variables are inside.
These are not just API calls. They are operating patterns. When those patterns are built into the MCP server, the agent becomes less like a generic HTTP client and more like a careful assistant that has been taught how Survey Solutions work is actually done.
That is where domain expertise matters. As experienced Survey Solutions users, we can define higher-level workflows that match the real decisions survey managers, data managers, and statisticians need to make. The MCP server becomes a way to package that expertise so an AI agent can use it consistently.
Testing An MCP Is Different
Testing an MCP server has two layers.
The first layer is conventional software testing. The code still needs to compile. Tool schemas need to validate. Mock servers need to return stable responses. Smoke tests need to confirm that every registered tool can be discovered and called. Installer scripts need to work on the target operating system. Credentials must not leak into configuration files or logs. Dangerous actions need guardrails.
The second layer is more unusual: the MCP is effectively a product for an LLM to use.
That means it needs to be tested by LLMs themselves. The question is not only "does the function return JSON?" It is also "can an agent understand when to use this tool?", "does the tool name make sense?", "does the error message help the agent recover?", "does the output contain enough context for the next step?", and "does the workflow steer the agent away from risky actions?"
Then there is user testing. Even if an agent successfully calls the tool, the resulting action or recommendation must still make sense to a human Survey Solutions user. If an AI agent creates a web interview assignment, downloads an export, or recommends a permission change, the output needs to match how a real project team would expect the system to behave.
So the testing loop is two-fold:
- LLM testing checks whether the agent can discover, understand, and use the tools reliably.
- User testing checks whether the outputs, actions, and workflow decisions are correct in real operational terms.
Both are necessary. One without the other is incomplete.
Why Open Source Fits This Work
Survey operations vary enormously. A national statistics office, an NGO research team, a World Bank project, and an independent evaluation firm may all use Survey Solutions differently. They may have different permission models, export formats, naming conventions, fieldwork structures, and reporting needs.
That makes open source a natural fit.
An open Survey Solutions MCP server can be improved by the community. Teams can add new workflows, adapt tools to their own operating procedures, audit the safety model, contribute better documentation, and extend the server as new AI clients and Survey Solutions APIs evolve.
It also supports the way Impact Engines wants to work. Our focus is practical, responsible AI for organisations working in development, humanitarian, and public-sector contexts. We are interested in AI that makes expert users more effective, not AI that hides complexity behind a black box. Open tooling makes that possible: people can inspect it, adapt it, and build on it.
Where This Goes Next
The current Survey Solutions MCP server already provides a useful local bridge for agent-assisted Survey Solutions work: profile management, safe read workflows, guarded write actions, exports, export inspection, first-pass QC signals, diagnostics, and guided census style setup.
The next step is to keep testing it in real workflows. We want to learn which tool outputs help agents make good decisions, which workflows should become higher-level prompts, and where human confirmation is essential. Over time, the goal is a practical open-source layer that lets AI agents support survey teams without bypassing the judgement of the people responsible for the data.
That is the point of the project: not an AI agent that vaguely knows about surveys, but an AI agent with a well-designed, auditable, expert-built bridge into the systems survey teams actually use.
The Survey Solutions MCP server is open source on GitHub: https://github.com/lbruce-wq/survey-solutions-mcp.