Every test was green. The calls returned what they should, the permissions held, the data was right. Then an AI agent that had spent an hour with the first version of our MCP server gave us its verdict: using it was unpleasant.
It had counted the cost. Three round trips and a credential to handle before doing one thing, when all it wanted was to do the thing.
Tests measure whether something works. That sentence measured something else: how it feels to use. It is the complaint of a developer who drops a clumsy SDK halfway through an integration, and it came from a machine.
This post is about the feature that agent was using, how we came to interview it, and what we changed after listening.
The feature: your data as an MCP server, with no code
MCP, the Model Context Protocol, is how AI assistants such as Claude, Cursor or VS Code reach an external system. Until now, putting your data in front of an agent meant writing an MCP server of your own: tools, schemas, authentication, and a deployment to keep running.
In RESTHeart Cloud every service is now an MCP server. Getting an agent to use it takes three steps:
- Publish what the agent may use. Collections, aggregations, change streams and GraphQL apps can all be published. For each one you write a sentence saying what it holds, for example "Customer orders, one document per order, with status and total." The agent reads that sentence to decide whether this is the data it wants.
- Give the agent a credential. A user of your service issues an API key with a role you chose. To try it out, Quick test setup → Do all creates a test user, its permission, a test collection and a key in one click.
- Connect the client. In Claude, add a custom connector and paste the endpoint. In Cursor or VS Code, paste the snippet the console shows you, with the key already in it.
Then ask "How many orders are still open?" The agent finds orders in the catalogue, reads it and answers. From an existing service to a working agent takes about ten minutes.
The agent can do exactly what its role can do over REST. Permissions, read filters and projections apply to MCP as they do to any other request. Two users who connect the same agent see two different catalogues, each limited to what their own permissions could allow. A resource stays invisible until you publish it, and publishing it grants nothing beyond the permissions you already wrote.
The MCP Server documentation covers every detail.
How we tested it: a game played by agents
We tested every call, and every call worked. Those tests leave one question open: can an agent that has never seen the API get something done with it?
To answer it we built a small multiplayer game. Three agents trade items, make and accept offers, and each pursues a private objective. They play through the MCP server alone, with no client library and no code written for the game. On the server there is one collection and six permission rules. Each agent receives a brief with the goal and almost nothing about the means. To make an offer, it first has to discover that offers exist.
A match replayed: three agents, each with a private objective, trading through the MCP server alone. The standings, the offers and the round log are read from the same collection the players write to.
A goal and an opponent give the agent something to want. An agent that is losing explores. After a failed attempt it tries another way, and when a round depends on a description it reads that description carefully. A test script never produces this behaviour, and it is the behaviour we needed to see.
When the match ends, every player answers the same questionnaire. Asked how it went, an agent writes a pleasant report with nothing useful in it, so every question asks for evidence:
- What did you call to find out what exists, and when did you know enough to act?
- Did you try something that was not there? Did you see something you could not use?
- Which description was wrong or incomplete? Quote it.
- Every refusal you received, word for word, and whether it told you what to do next.
- What did you have to guess?
- If you could change one thing, what would it be, and what did it cost you today?
An agent can answer at this level of detail. It remembers every call and every response, and it quotes the exact sentence that misled it.
The market game is open source, as a full tutorial you can run against your own service.
The sentence that changed the design
Our first design gave the agent three tools. The first listed what exists. The second composed the exact request for an operation, with method, URL and body, and a placeholder for the credential. The third issued a short-lived token. The agent filled in the placeholder and made the call itself.
On paper the design was clean. The server described, the client executed, and no one held more than a token that expired within a minute. Every test we wrote checked that the pieces worked, and they all passed.
None of those tests asked whether doing a job this way was pleasant. An agent raised the question on its own, and answered it: three calls and a token to do one thing.
So we redesigned it. The agent now acts through a single tool. It names the resource, the action and the arguments, and the server performs the call itself, with the same authentication, permissions and pipeline as any other request. The token tool is gone, and credentials stay on the server.
The agent makes one call where it used to make three, and it holds no credential at all. It is also exactly what the agent asked for.
Dozens of matches, and many small findings
That sentence was the loudest finding. We then ran dozens of matches, each followed by the same interview, and collected a long list of smaller ones. Each made the API a little easier to use.
A few examples:
- A player concluded the service was read-only and gave up on writing. The write was permitted and would have worked, but the catalogue did not list the action. A resource is now described with every action the caller's permissions could allow.
- Descriptions were accurate and incomplete. The agent read them, drew a reasonable conclusion, and got it wrong. Each time it quoted the sentence, and we rewrote it.
- Aggregation parameters had no description. An agent facing an undescribed parameter guesses. The console now asks for a type and a description for each one.
Added together, these are what separate an API an agent manages to use from one it is comfortable with.
Testing with the users themselves
The shape is familiar from user research: people perform a task, then they are interviewed. Here the test population and the user population are the same population.
User research recruits people who resemble your users, and draws inferences from them. In our case the participants are the same kind of client that will call the API in production, doing the same kind of work. When one of them struggles, a real user is struggling.
A full round, with several players, a whole match and structured interviews, takes an afternoon of compute. At that cost it can run on every significant change, while acting on the answer is still cheap.
What it does not tell you
Agents differ. A finding from one model is evidence about that client. Where a decision matters, run the test with more than one.
Agents also read documentation far more patiently than a developer integrating an API by hand. A catalogue that an agent copes with may still frustrate a person.
The method also depends on discipline. Asked how it went, an agent will say it went well. Questions that demand quoted evidence are what make the report useful; without them it is worthless, and worse, it reassures.
Try it
MCP is in beta on every RESTHeart Cloud service, free tier included. Open your service, go to MCP Server, click Quick test setup → Do all, and connect Claude. In about ten minutes an agent can answer questions about your data, within your permissions and with no code.
Dozens of matches, and one blunt agent, shaped the version you will be using.
Ready to Build Something Great?
Focus on what makes your app unique. Your backend is ready in minutes. Start with our free tier - no credit card required.