MCP (Model Context Protocol) servers are quickly becoming a crucial layer between software systems and AI agents.  In the context of systems that already expose a public API, MCP servers can be positioned as proxies, translating standardized API specifications into structured data that AI can easily consume. Done right, MCP servers allow AI agents to interact with external platforms, access data, trigger workflows, and perform complex operations—all while staying decoupled from the underlying system. 

But here’s the catch: building MCP servers isn’t just about wrapping your API in a shiny new layer. If you do it naively, you’ll expose too much, risk security, and run into schema nightmares. 

In his talk at the Shift Zadar 2025 conference, Filip Srnec, a Principal Engineer at Infobip, shares how Infobip approached the topic of creating their MCP servers, focusing on OpenAPI, schema design, and tricky features that can make or break your implementation. 

Filip Srnec on Shift Zadar 2025
Filip Srnec giving his talk, How Can Agents Communicate. Unlocking AI Interactions with Infobip MCP Servers.

The Core Idea: MCP as a Decoupled Layer 

At its heart, an MCP server is another interface to your platform. AI agents can connect to the MCP layer. And in turn, the MCP layer can communicate with your core API stack. This means MCP can be fully decoupled—not just a wrapper glued onto the existing endpoints. 

To scale the MCP servers, the natural question arises: can we deploy them dynamically from APIs? The answer is yes— by leveraging the OpenAPI specification. 

OpenAPI: Your Blueprint for MCP Servers 

OpenAPI gives you a formal, machine- and human-readable way to describe HTTP APIs. 

It’s the perfect foundation for MCP because it provides a clear and standardized way to translate API endpoints into tools that AI agents can understand and use. 

MCP Tool official specification
Official MCP tool data type specification

The goal is one-to-one correspondence: every MCP operation should directly map to an API operation. 

MCP Tool in OpenAPI spec context
An example of how to match API operations to the MCP tool data type specification.

But this doesn’t mean you should just expose your entire API spec to AI. That could result in suboptimal agentic experience. 

Filip stresses this point several times in his talk: build your MCP to match the AX you are after, rather than throwing everything you’ve got at it.

Curate what’s exposed, rewrite descriptions with context, and even restructure certain endpoints. 

The Discriminator Problem

According to Filip, one of the most powerful—but also challenging—parts of OpenAPI is the discriminator. 

MCP tools use standard JSON Schema, while OpenAPI’s version is a superset that includes features such as discriminators. We therefore need to translate discriminators into the standard JSON Schema format as effectively as possible. 

Let’s say your API, just like Infobip’s, supports sending messages using Viber or RCS. A single endpoint might handle multiple message types: text, images, video, files. The discriminator lets you define a property  (e.g., “type”: “image”) that determines which input schema to use.

Example of how to use a discriminator
An example of how to use a discriminator with a defined property.

In theory, this is elegant. In practice, it introduces several challenges: 

  • Validation complexity – The MCP server or the underlying platform needs to interpret the polymorphic input correctly. 
  • Agent usability – If you don’t process the discriminator carefully, the AI may get confused about which type to select. 

One practical way to mitigate the discriminator problem is by using the oneOf method in your schemas to bring them closer to the official JSON schema standard. This makes the schema easier for MCP servers to process and for AI agents to match, since the available options are explicit and self-contained. 

And that’s exactly what matters most. The ability to provide accurate schemas in tool definitions, so that agents can reliably handle polymorphic schemas. 

discriminator flattening
The oneOf method brings a schema closer to the official JSON schema standard, thereby bypassing the discriminator problem.

Best Practices for Building MCP Servers using the OpenAPI specification

  1. Curate your OpenAPI spec 
    Don’t expose every endpoint. Filter, rewrite, and annotate with context that helps AI agents, not developers. 
  1. Handle schema composition carefully 
    Merge parameters (query, headers, body, cookies) into a clean, unified input schema. Keep it simple for the agent. 
  1. Use discriminators wisely 
    Always provide clear examples for each type. Make sure the discriminator field is intuitive and consistent. 
  1. Resolve $refs up front 
    Inline schemas reduce complexity for the MCP consumer. 
  1. Plan for authentication 
    MCP servers sit in front of your APIs—they’re not auth servers. Reuse the existing platform authentication, but design filters to securely pass tokens or credentials downstream. 

Wrapping Up 

MCP servers are on the rise—but the real value comes when they’re built with intention. Using OpenAPI as the foundation and handling tricky constructs with care makes all the difference. 

Get it wrong, and your agents will run into broken schemas, security risks, and inconsistent experiences. Get it right, and you’ll have a scalable, AI-friendly interface that unlocks your platform’s full potential. 

Following that exact logic, Infobip MCP servers give your AI agents communication superpowers—from sending a WhatsApp template message to managing customer data. Filip’s talk, which covers many more valid points of creating MCP servers, will soon be available on Shift’s YouTube channel. Stay tuned, Folks! 

You can also secure your spot on the next year’s Shift Zadar conference, 13-15 September 2026, or attend the last Shift conference of the year in Kuala Lumpur, 3-5 November 2025.