Building an Analytics MCP Server: Wrapped API vs Semantic Layer

Building an analytics MCP server requires choosing between wrapping an existing API or implementing a semantic layer. Wrapping an API is faster but leads to inconsistent metrics and chatty queries, while a semantic layer provides a single source of truth for metrics and dimensions. The decision impacts correctness, consistency, and scalability for AI agents querying product data.

← All posts /blog Building an Analytics MCP Server: Wrapped API vs Semantic Layer You’ve decided to let AI agents read your product’s data through the Model Context Protocol. The next decision is quieter, but it matters more than it looks: what does the agent actually query? There are two answers, and they lead to very different servers. The first is to wrap your existing API : take the REST or GraphQL endpoints you already have and expose them as MCP tools. The second is to put a semantic layer underneath the server, so the agent queries defined metrics and dimensions instead of endpoints or tables. Both produce a working read MCP server. They diverge on everything that decides whether that server is trustworthy in front of real users. This post compares them on the dimensions that matter, and lays out when each is the right call. First, what a “read” MCP server is doing An analytics read MCP server exposes tools an agent can call to retrieve data, with no writes and no side effects. The agent discovers what’s available, forms a query, and gets structured results back. The hard part isn’t the retrieval. It’s making sure the agent asks answerable questions, gets answers that are correct and consistent , and only ever sees data it’s allowed to. The two architectures below handle that very differently. Approach 1: Wrap your existing API The pitch is speed. You already have endpoints like /orders , /users , and /usage , with auth, pagination, and filtering. Wrapping them as MCP tools is mechanical: one tool per endpoint, pass the parameters through, return the JSON. What’s good about it: Fastest path to a working server. If the API exists, you can expose it in hours. Reuses existing auth and permissions. Whatever access control your API already enforces comes along for free. No new data infrastructure. You’re not modeling metrics or standing up a query layer; you’re forwarding calls. Where it breaks down: Agents have to assemble analytics from endpoints. Your API was designed for application developers who read the docs, not for an agent answering “what was net revenue by region last quarter.” The agent has to fetch orders, filter, join, aggregate, and define “net revenue” itself. It will define it inconsistently across calls. No shared definition of a metric. If “active user” is computed one way in your billing endpoint and another way in your usage endpoint, the agent can produce numbers that contradict each other and your own dashboards. There’s no single source of truth, just endpoints. Chatty and expensive. Analytical questions often require many endpoint calls plus client-side aggregation. That’s slow, token-heavy, and it multiplies under autonomous agents that query far more than humans. Leaky surface area. Endpoints expose your internal resource shapes. Agents will discover and lean on fields you never intended as an analytics contract, and every future API change risks breaking them. Pagination and row limits fight aggregation. APIs page results for UIs, but agents doing aggregation want the aggregate, not 40 pages of rows they have to sum themselves. Wrapping an API hands the agent a filing cabinet and asks it to be the analyst. It works for simple lookups and falls apart on real analytical questions. Approach 2: Put a semantic layer underneath A semantic layer sits between your databases and the MCP server. It defines your metrics net revenue , active users , churn rate , your dimensions region, plan, time grain , and how they’re computed, once and centrally. The MCP server exposes those as the query surface. The agent asks for a metric, sliced by dimensions, over a time range, and the layer generates the correct query and returns the aggregate. What’s good about it: One definition of every metric. “Net revenue” means exactly one thing whether the agent asks, your dashboard renders it, or a report exports it. The answers stay consistent. Agent-shaped query surface. The agent picks from a discoverable set of metrics and dimensions instead of reverse-engineering analytics from endpoints. Questions map cleanly to queries. Aggregation happens where it should. The layer computes aggregates in the database and returns compact results, so you get fewer round trips, lower token cost, and faster answers. Governance is centralized. Access rules, row-level security, and what’s exposed all live in one place instead of scattered across endpoints. This is what makes multi-tenant, customer-facing access defensible. Stable contract. The metric surface is a deliberate contract. You can refactor the underlying tables without breaking the agent, because the semantic definitions are the interface. Where it costs you: Upfront modeling. You have to define your metrics and dimensions. That’s real work, and it forces decisions “what is our official definition of an active user?” that teams sometimes haven’t made. New infrastructure to run. A semantic layer is a component to operate and keep in sync with your data, unless you use a managed platform that provides it. The semantic layer gives the agent a clear vocabulary of metrics to work with. It takes longer to set up, but it does the real job far better. Head to head | Dimension | Wrapped API | Semantic layer | |---|---|---| Time to first working server | Hours | Days modeling required | Metric consistency | None; agent defines metrics ad hoc | Guaranteed; one definition | Answer correctness on real questions | Fragile; depends on agent’s joins | Reliable; queries are generated correctly | Query efficiency / token cost | Chatty, aggregates client-side | Compact, aggregates in-database | Governance & multi-tenant security | Scattered across endpoints | Centralized, enforceable | Stability under change | Breaks when API/schema shifts | Stable contract; refactor underneath | Best for | Simple lookups, internal tools, prototypes | Customer-facing, analytical, production | When each is the right choice Wrap the API when the questions are simple lookups “get this record,” “list these items” , the audience is internal or a single trusted tenant, and you need something working this week. It’s a legitimate prototype and a fine answer for narrow, non-analytical retrieval. Use a semantic layer when agents need to answer real analytical questions, when consistency with your product’s own numbers matters, and, above all, when the agents belong to your customers . The moment access is multi-tenant and customer-facing, centralized governance and one source of truth are no longer optional. If an agent leaks a field or reports revenue that disagrees with your dashboard, that’s a trust and security problem, not a minor rough edge. The pragmatic path Many teams start by wrapping an API to learn what agents actually ask, then hit the wall: inconsistent numbers, runaway query counts, and governance they can’t defend in a security review. At that point they move the real workload onto a semantic layer. If you already know you’re heading for customer-facing, analytical access, you can skip the detour. This is the layer we build at Motley. SLayer, our open-source semantic layer, is where you define your metrics, dimensions, and business context once, so every consumer computes them the same way. Motley is the hosted platform on top: it runs the multi-tenant read MCP endpoint your customers’ agents query, with consistent answers, in-database aggregation, per-tenant security, and audit built in. You get the semantic-layer outcome without building and operating the semantic layer yourself. The wrapped API gets you a demo. The semantic layer gets you something you can put in front of customers. Building agent access to your product’s data? Talk to us about doing it on a governed semantic layer from day one.