# Infobip Openapi Mcp > Infobip OpenAPI MCP is a framework for exposing OpenAPI documented HTTP APIs as MCP servers. It is based on Spring AI and made to run as a Spring Boot application. It is powering Infobip's own MCP servers, and you can use it to implement your own MCP servers. - **Type:** MCP server - **Install:** `agentstack add mcp-infobip-infobip-openapi-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [infobip](https://agentstack.voostack.com/s/infobip) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [infobip](https://github.com/infobip) - **Source:** https://github.com/infobip/infobip-openapi-mcp ## Install ```sh agentstack add mcp-infobip-infobip-openapi-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # OpenAPI MCP OpenAPI MCP is an open-source framework for exposing any [OpenAPI][1]-documented HTTP APIs as [MCP][2] servers. Built on [Spring AI][3] and designed to run as a [Spring Boot][4] application, it's already running in production, powering [Infobip MCP servers][5]. It's production-tested and ready for you to use in your own projects! ## Features The framework is a bridge from the OpenAPI described APIs to MCP servers. Core functionality is mapping HTTP API operations (paths and HTTP methods) to MCP tools. This includes a setup step that happens upfront to prepare tool metadata which is presented to AI agents and a runtime step that happens when AI agents invoke tools. Some of the core features include: - Adapting OpenAPI specification to work with MCP tools. APIs have more flexibility in their inputs, e.g. they accept path and query parameters, while MCP tools expect to receive all inputs as a single JSON object. The framework will detect these cases and wrap / unwrap inputs accordingly. - OpenAPI specification allows advanced features in request schema definitions, such as discriminators for polymorphic models. This is not allowed in pure JSON schema used by MCP, so the framework has a transformation step in which discriminators are resolved and embedded in a way compatible with JSON schema. - Mock mode in which MCP server returns examples from the OpenAPI specification instead of making HTTP API calls > [!IMPORTANT] > The OpenAPI MCP framework allows you to expose any HTTP API documented with OpenAPI to LLM agents. Since LLMs will > process the API responses it is important that you trust the API won't compromise your users' agents with prompt > injections. It is equally important to trust the OpenAPI specification, as it is used as a source of meta-data that is > directly provided to LLMs. When exposing your own APIs make sure that responses are secure and can't be used to inject > untrusted text that might contain prompt injection. When exposing 3rd party APIs make sure the API itself is trusted, > but also that the OpenAPI specification which defines it is equally trusted. When working with 3rd party OpenAPI > specifications you can review and store them as a static files inside your application resources. That way you can be > sure specifications won't change unexpectedly. ### Authentication Authentication and authorization is important for MCP servers, and can be tricky to implement. In case of exposing HTTP APIs as MCP tools the security posture of the API is bases for everything. The OpenAPI MCP framework adapts it to MCP specification in few key ways: - The framework exposes required `/.well-known` HTTP endpoints. Two of them (`/.well-known/openid-configuration` and `/.well-known/oauth-authorization-server`) are proxied to your [authorization server][5], and one (the `/.well-known/oauth-protected-resource`) is handled by the framework itself. - There is the option of supporting authorization checking API endpoint that framework invokes before processing MCP interactions to validate client credentials. Lastly, by delegating authentication to dedicated API endpoint, the framework supports arbitrary auth type, such as classic API key and Basic auth types, in addition to OAuth. There are more technical features that enable customizing various behaviors, like: - OpenAPI filters that can be used to programmatically customize the specification before MCP tool metadata is constructed. - [OpenAPI extensions][7] that can be used to customize different aspects of MCP tools, including listing custom OAuth scopes. - Several naming strategies are available to customize MCP tool names. - API request enrichers that can be used to programmatically customize the API requests that back the tool calls. - MCP tool call filters that can be used to customize tool call behavior. - A base of [Spring AI][3] external customization options, which framework builds on top of with its own options. See below for a full list. ## Getting Started ### Prerequisites OpenAPI MCP framework requires Java version 21 of newer, and is based on [Spring Boot][4] `3.5.x` and [Spring AI][3] `1.1.x`. ### Installation You can install it in your Java project with maven: ```xml com.infobip.openapi.mcp infobip-openapi-mcp-spring-boot-starter 0.1.16 ``` or gradle: ```groovy implementation("com.infobip.openapi.mcp:infobip-openapi-mcp-spring-boot-starter:0.1.16") ``` ## Usage After installation enable one of the [server protocols supported by Spring AI][8] with externalized configuration properties. For example, you can enable [stdio transport][9] with a config like this: ```yaml spring: ai: mcp: server: type: sync stdio: on ``` > [!IMPORTANT] > Make sure to set the server type to `sync`, as some of the framework features (such as authentication) will not work > with the `async` type. To expose a remote server using the currently recommended [streamable HTTP transport][10] use this config: ```yaml spring: ai: mcp: server: protocol: STATELESS ``` ## Configuration ### OpenApiFilter You can implement and register beans of type `com.infobip.openapi.mcp.openapi.filter.OpenApiFilter` to change the OpenAPI specification before framework extracts MCP tool meta-data from it. Individual filters can be disabled in externalized configuration with the `infobip.openapi.mcp.filters.[filter-name]` property. For example, to disable the built-in filter that removes regex pattern property from OpenAPI schemas set `infobip.openapi.mcp.filters.PatternPropertyRemover: false`. > [!TIP] > AI agents perform best with smaller, focused MCP servers. On the contrast, HTTP APIs are ofter large and full of > different features. This means we usually need to pick a subset of API operations that will be included as tools. > Sometimes we need to also pick a limited subset of input parameters like query parameters or even request body > properties. There are two ways to prepare OpenAPI specification for this: > > 1. You can make a dedicated OpenAPI specification for your MCP servers. This can be done either from scratch, or by transforming the original specification with something like [OpenAPI overlays][12]. This transformation can be automated as part of your CI pipeline. In this case your MCP server will receive the limited-scope specification with only the elements that you selected to expose to AI agents. > 2. Alternatively, you can provide MCP server with the original, fully featured specification and narrow down its scope by implementing OpenAPI filters in your application code. > > Both approaches can be combined. ### Tool NamingStrategy MCP servers expose functionalities to AI agents as tools. Each tool is identified by a name which is accompanied by a description. LLMs pick tools to use based on this information, so it is important to make them concise and clear. The framework implements several strategies for naming tools: 1. `OperationIdStrategy`, which produces names based on `operationId` from OpenAPI specification. 2. `SanitizedOperationIdStrategy` which uses `operationId`, but sanitizes it by lowercasing alphanumeric characters and replacing others with underscore. 3. `EndpointStrategy`, which combines HTTP method and path. Various MCP client libraries have different limitations on the maximum tool name length. To accommodate this the framework provides `TrimNamingStrategy`, which wraps one of the base strategies and enforces length limits on top of it. You can customize tool naming with `infobip.openapi.mcp.tools.naming.strategy` and `infobip.openapi.mcp.tools.naming.max-length` external configuration properties. If provided implementations do not meet your needs you can provide your own implementation. > [!TIP] > Many MCP client libraries implement scoping of tool names. Common pattern is to allow client applications to name each > MCP server they connect to, and to prepend the server name to names of tools loaded from the server. This means you as > MCP server developer do not need to scope your tool names. It is best to keep names short and to the point. ### Tool descriptions LLMs pick tools based on their names and descriptions. In order for them to be able to do that descriptions of all tools from all MCP servers that an agent is connected to are loaded into LLM context. This means that tool descriptions need to be as short as possible while retaining clarity, but not shorter than that. The OpenAPI MCP framework can use few API operation properties to create tool descriptions. It can either take just the operation summary, or it can combine it with operation description. The behavior can be controlled with `infobip.openapi.mcp.tools.prepend-summary-to-description` externalized configuration property. The framework can also append a request example to each tool description as a Markdown JSON code block. Examples are extracted from the OpenAPI specification — from parameters and request bodies — and combined into a single object mirroring the tool's input schema structure. The behavior is controlled by the `infobip.openapi.mcp.tools.examples-mode` property, which accepts three values: - `SKIP` (default) — no examples are appended. - `ALL` — all examples from the OpenAPI specification are included. - `ANNOTATED` — only examples explicitly marked for MCP use are included. Mark an example by adding `x-mcp-example: true` directly on the OpenAPI `Example` Object (inside the `examples` map of a parameter or request body): ```yaml examples: basicRequest: summary: Basic SMS x-mcp-example: true value: to: "41793026727" text: "Hello" advancedRequest: summary: Advanced SMS (not shown in MCP) value: to: "41793026727" text: "Hello" validityPeriod: 720 ``` > [!TIP] Be mindful that examples add to the context size consumed by tool descriptions. If the examples in your OpenAPI > specification are large or numerous, `ANNOTATED` mode is the recommended approach — it lets you selectively expose > only the examples that are most useful for the LLM, without needing OpenAPI overlays or custom filters. ### Tool annotations MCP tools support [annotations][15] that describe their behavior to MCP clients. The framework automatically infers annotations from the HTTP method of each API operation: | HTTP Method | `readOnlyHint` | `destructiveHint` | `idempotentHint` | `openWorldHint` | |--------------------|----------------|-------------------|------------------|-----------------| | GET, HEAD, OPTIONS | `true` | `false` | `true` | `true` | | PUT | `false` | `false` | `true` | `true` | | POST | `false` | `false` | `false` | `true` | | DELETE | `false` | `true` | `true` | `true` | | PATCH | `false` | `false` | `false` | `true` | `openWorldHint` is always `true` because every tool calls an external HTTP API. Annotations can be overridden per-operation using the `x-mcp-annotations` [vendor extension][7] on the OpenAPI Operation object: ```yaml paths: /messages: post: operationId: sendMessage x-mcp-annotations: idempotentHint: true ``` They can also be overridden globally per tool name using externalized configuration properties: ```yaml infobip: openapi: mcp: tools: annotations: sendMessage: idempotent-hint: true ``` Override precedence (lowest to highest): HTTP method defaults, `x-mcp-annotations` vendor extension, YAML configuration properties. Each layer only overrides fields it explicitly sets; unset fields fall through from the previous layer. ### Authentication MCP defines OAuth as preferred authentication method. The framework aims to make this as easy to implement as possible. There are few considerations when exposing existing APIs: 1. The underlying API must implement the same authentication type as MCP server. 2. There are few specifics of MCP specification that need to be satisfied for clients to work automatically. One of MCP requirements is that first interaction with MCP server that doesn't include valid credentials should be rejected; in fact that is what triggers the login flow in MCP clients. However, this interaction is usually not direct tool invocation, meaning that the framework does not need to make any API calls to implement tool calls. Since credentials still need to be verified framework needs to invoke some API endpoint which only performs the authentication. This special endpoint, which is not exposed as a tool but is used only in this auth flow, needs to be defined in an externalized configuration property `infobip.openapi.mcp.security.auth.auth-url`. This is needed whenever security is enabled. The framework will pass any `Authorization` header from the inbound MCP request to the `auth-url` endpoint on the API. #### OAuth MCP specification defines a flow for automatic [authorization server discovery][13]. One of the requirements is that MCP server itself should expose few `/.well-known` HTTP endpoints defined by the OAuth specification. Some of these are usually implemented by the OAuth authorization server, and the OpenAPI MCP framework can proxy those calls to make it more convenient to expose them from the same server as the rest of MCP features. Some endpoints are implemented and exposed directly by the framework, as in acts as OAuth resource server. OAuth APIs usually rely on scopes for fine-grained access control, and MCP specification allows for this. OpenAPI MCP framework takes the OAUth scope information from the provided OpenAPI specification. The framework looks for scopes either in standard security properties or in custom operation-level OpenAPI extensions that can be defined in `infobip.openapi.mcp.security.auth.oauth.scope-discovery.scope-extensions`. Additionally, fixed, predefined scopes can also be defined with `infobip.openapi.mcp.security.auth.oauth.scope-discovery.mandatory-scopes`. You can configure what set from all discovered scopes are requested during login by setting the externalized configuration property `infobip.openapi.mcp.security.auth.oauth.scope-discovery.calculate-minimal-scopes`. When `NONE` is used, which is the default, all discovered scopes are requested. When `GREEDY` is used an optimistic greedy algorithm picks a subset of scopes which still covers all operations. ### ApiRequestEnricher If you need to customize HTTP requests that the framework is making towards the API you can implement and register beans of type `com.infobip.openapi.mcp.enricher.ApiRequestEnricher`. This is a good place to include any meta-data for monitoring or custom tracing that you may need. Framework provides few enrichers out of the box, for example the one that sets the `User-Agent` header to the value defined in externalized configuration property `infobip.openapi.mcp.user-agent`. > [!NOTE] > Implementations of API request enrichers should be lightweight and non-critical. The framework will skip enrichers > that fail by catching any exceptions and carry on to make the API request. This is why the enricher interface is > limited > to tweaking Spring's `RestClient.RequestHeadersSpec` and does not provide options to break the flow and prevent the > API > call from being made. ### CredentialProvider The framework uses `com.infobip.openapi.mcp.auth.CredentialProvider` to obtain the credential value used for authenticating incoming requests and forwarding authorization to the downstream API. The default implementation reads the `Authorization` header from the incoming HTTP request. You can replace this bean to supply credentials from any source: ```java @Bean public Credent … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [infobip](https://github.com/infobip) - **Source:** [infobip/infobip-openapi-mcp](https://github.com/infobip/infobip-openapi-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-infobip-infobip-openapi-mcp - Seller: https://agentstack.voostack.com/s/infobip - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.