How We Built Trophy's MCP Server: What We Let AI Agents Do, and What We Didn't

Trophy is gamification infrastructure for consumer apps. Product teams use its APIs and SDKs to add achievements, streaks, points, leaderboards and personalised notifications without building the backend systems themselves. Trophy also runs two remote MCP servers, so AI agents such as Claude, ChatGPT and Cursor can read Trophy's documentation and configure a live Trophy account from chat.

This post covers how we built those servers, what the tools actually do, where we let an agent act on its own, and the things we deliberately kept out of an agent's reach. If you're deciding whether to let an agent do real work through a tool, the decisions are the useful part, and they rhyme closely with the ones DokuTrak made for its own connector.

Key takeaways

• Two servers, two jobs. A read-only Docs MCP server gives agents live documentation. A separate Account MCP server is the action layer that changes account configuration.
• Reads are free, writes are scoped. Every write happens inside one authorised organisation and one named environment.
• We kept destruction out of the toolset. Almost no tool can delete anything. The one exception removes a temporary streak pause.
• The agent works in chat; production code uses the API. The MCP server is for people and agents working interactively, not for backend jobs.

Why build an MCP server at all?

Setting up gamification in Trophy has always meant two kinds of work. The first is code: sending events from your app to Trophy's gamification API. The second is configuration: deciding which user actions count as metrics, how many points a workout is worth, when a leaderboard resets, what unlocks an achievement. Configuration lived in a dashboard, which meant looking at screens and clicking buttons.

Most teams we work with now ship product work inside AI coding agents, and configuration was the one part of a Trophy integration that still forced them out of that flow. Our goal: an agent should be able to work out what gamification a product needs, map it to Trophy's features, and set it up without anyone copying dashboard steps into chat.

We got there in stages: an Admin API for account configuration in April 2026, public OpenAPI specs in May so coding agents always had current information, and the MCP servers on top of that foundation.

Two servers, two jobs

The single most important design decision was splitting knowledge from action.

An agent that knows how a feature works is far less likely to misconfigure it. So our recommended workflow runs in a fixed order: load the relevant docs, read what already exists in the account, write only what the task requires, then verify. Keeping the servers separate means a team can connect the Docs server alone with zero risk, and add the Account server only when they're ready for an agent to act.

DokuTrak made an equivalent cut in a different place. Its connector lets an agent create, read, chase and collect document requests, but sits entirely on the side of the workflow that gathers information. The judgement call stays elsewhere.

What the tools actually do

The Account MCP server exposes paired read and write tools for most parts of a Trophy account. Write tools create or update in batch, so an agent can set up a whole points system in one call instead of dozens.

In practice, people talk to it in plain language. A few real example prompts from our documentation:

• "Create an XP system called 'Kudos' that grants 10 points for each workout completed."
• "Schedule 2X XP boosts for the 'Kudos' system across the next 3 weekends, only for paying users."
• "List all achievements, completion rates and rarity in my Trophy account."
• "user_123 wants their streak back, restore it to its previous length."

Restoring a broken streak is a support task, not an engineering task, and now it takes one sentence. For the full picture of how freezes, pauses and restores work, see our streaks feature page.

Where the agent acts on its own

We were comfortable letting an agent act without a confirmation step inside Trophy when three conditions held:

1. The action is scoped. Access is limited to the one Trophy organisation the user authorised during OAuth sign-in. There are no API keys for an agent to leak or misuse, because the Account server uses OAuth rather than keys.
2. The action targets a named environment. Every tool acts on a specific environment. If an account has only one, it defaults to it. If it has several, the agent must pass the environment key or list them first. We recommend iterating in a staging environment before touching production.
3. The action is recoverable. Creating or updating a leaderboard can be undone by updating it again. Granting a streak freeze is additive.

That third condition is the one that matters most, and it's where our situation differs from DokuTrak's. DokuTrak's key side effect is an email to a real client, which can't be recalled. That's why DokuTrak's connector asks the user to confirm before a document request is emailed to a client. Trophy's writes change configuration, which a person can inspect and revert. The lesson generalises: match the amount of friction to how reversible the side effect is.

What we chose not to automate

The more interesting design work was in what we left out.

Deletion. Most tools cannot delete resources. An agent can create and update a leaderboard but cannot remove one. The single exception is delete_streak_pauses, which removes a temporary pause on a user's streak. Deleting a metric or points system could silently break an app in production, and no chat-based convenience is worth that.

Production integrations. The Account MCP server is designed for chat and agent workflows. Scripts, backend jobs and anything running unattended in production should call the Admin API directly, with its own keys and its own error handling. An MCP server is a great interface for a person working with an agent, but a poor foundation for a cron job.

This mirrors DokuTrak closely. Its connector never exposes approving or rejecting a client's document as a tool, and the service refuses those actions to any agent connection regardless of which connector asks. Billing, workspace settings and API key management are off-limits too. The principle is the same in both products: the agent does the legwork, a person keeps the decisions that carry consequences.

How agents tell us which tools are missing

We didn't want to guess what to build next, so we designed the Account MCP server to report back on how it's being used.

Every tool call carries a reason. Each Account MCP tool has a required context parameter: a short, third-person description of why the agent is calling it and how the call serves the user's goal, with no credentials or personal data. That gives us a running record of the jobs people actually use the server for, not just which endpoints get hit.

Agents can ask for a tool that doesn't exist yet. A get_more_tools tool invites the agent to describe its goal and the kind of tool that would help, even when an existing tool could work as a fallback. When an agent reaches the edge of the toolset, the request is recorded and submitted back to the Trophy team. A missing capability arrives as a written request instead of a silent workaround.

The docs server does the same for documentation. Its submit_feedback tool lets an agent report an incorrect, outdated or confusing docs page directly to our docs team.

The result is a feedback loop that runs in real time: we learn what users are trying to do from the agents doing it. If you're evaluating any agent tool, it's a fair question to ask the vendor: how do you find out what your users' agents couldn't do?

What surprised us once agents started calling it

Batch writes mattered more than we expected. An agent setting up a points system naturally wants to create the system, its triggers, its levels and its boosts together. Tools that accept nested, batched input turned a long chain of calls into one.

Analytics became a use case of its own. We built the server mainly for configuration. But reading tools like read_points_analytics and read_achievements_analytics meant product and growth people started asking questions of their data in chat, such as how points are distributed among paying users, without opening a dashboard or writing a query.

What this enables: automation, data access and agent workflows

For teams building consumer apps, connecting Trophy to an agent unlocks three things:

• Faster integration. A coding agent reads the docs, scaffolds the metrics, attributes and points systems in the account, then writes the matching event-tracking code in the app, all in one session.
• Easier access to data. Anyone on the team can ask for leaderboard rankings, achievement rarity or points distributions in plain language, filtered by user attributes such as subscription plan.
• Trophy inside larger agent workflows. Because it speaks MCP, Trophy can sit alongside other connectors. A support agent could restore a streak and log the ticket. A growth agent could schedule a weekend XP boost after reviewing engagement data.

It's the shift DokuTrak describes for professional firms: the repetitive work moves to the agent, and the professional reviews the outcome.

How to connect Trophy to your agent

1. Create a Trophy account.
2. Add https://docs.trophy.so/mcp to your MCP client as "Trophy Docs".
3. Add https://mcp.trophy.so/mcp as "Trophy Account", then sign in with OAuth and choose your organisation when prompted.
4. Ask your agent to review the docs for the feature you want, list what already exists, then create only what's missing.

Full setup guides for Claude, Claude Code, Cursor, ChatGPT and VS Code are in the Trophy MCP documentation.

---

Charlie Hopkins-Brinicombe is co-founder of Trophy. Trophy is the gamification layer for consumer apps, helping product teams increase user retention and engagement. Trophy's docs and MCP servers are at docs.trophy.so.