Exposing APIs to AI agents through MCP with APISIX

How to expose APIs to AI agents through MCP with Apache APISIX

A team that wants AI agents to call internal APIs through the Model Context Protocol (MCP) usually wants the gateway to decide who may call what, how often, and with which credentials. Apache APISIX has two plugins that touch this traffic: mcp-bridge, which is deprecated and scheduled for removal in a future release, and openapi-to-mcp, which appears in the plugin list alongside it. Neither should be treated as a settled foundation until the team has checked its current status, behavior and support in the exact APISIX version it plans to run. This page covers what MCP traffic looks like at the gateway, when a gateway layer adds value, how the two plugins differ, and what to confirm before relying on either.

MCP is a protocol that lets an AI client, such as an agent runtime or an IDE assistant, discover and invoke tools exposed by a server. The traffic is ordinary HTTP or streaming requests carrying tool discovery and tool call messages, so the gateway can authenticate the caller, apply rate limits and log each call much as it would for any other API. A gateway layer makes sense when several agents or teams share the same internal APIs, when agent identities must map to consumers with their own keys or tokens, or when a security team needs one place to enforce policy and audit tool invocations. It adds less value if the MCP server is a single internal process that only one trusted client reaches.

The mcp-bridge plugin connects MCP clients over SSE to a stdio MCP server that APISIX launches itself. Because it is deprecated, a new design should not depend on it without a migration path. The openapi-to-mcp plugin is the option to evaluate for exposing existing REST APIs as MCP tools, but the team should confirm which OpenAPI features it converts, how it handles authentication and whether it is maintained for its target release. Before a pilot, ask the plugin owner or APISIX community for written status, run the chosen plugin against a representative tool set, and verify that the authentication plugins in front of it (such as key-auth or jwt-auth) and per-consumer rate limits behave as intended. The APISIX mcp-bridge plugin documentation is the starting point for that check.

What the APISIX MCP plugins do today

APISIX ships two plugins aimed at Model Context Protocol traffic, and they are not at the same stage. One is deprecated and should not anchor new work, while the other is listed but needs confirmation against your target release. The cards below separate what each plugin does, what it leaves to you, and what to verify before you build on either.

The mcp-bridge plugin

The mcp-bridge plugin is deprecated and will be removed in a future release. It connects MCP clients over SSE to a stdio MCP server that APISIX launches itself, so the gateway takes on process lifecycle for the MCP server. Do not build new production flows on it. If you already run it, plan a migration path now and confirm the removal timing in the APISIX plugin documentation for your version.

The openapi-to-mcp plugin

The openapi-to-mcp plugin appears in the APISIX plugin list, which suggests it turns OpenAPI-described APIs into MCP tools that agents can call through the gateway. The listing alone does not tell you which OpenAPI versions, operations or parameter styles it handles. Confirm its behavior, supported specifications and version in your target release before you scope a pilot against it.

Deprecation and release planning

A deprecated plugin still runs, but its removal date depends on a future release that is not yet named in the sources we rely on. Map every MCP route to the plugin that serves it, then record the APISIX version each environment runs. Changes to plugin behavior often arrive with upgrades, so treat version pinning and staging tests as part of the MCP design, not an afterthought.

Authentication for agent clients

Agent clients act on behalf of users or services, so each one needs its own identity at the gateway. APISIX offers key-auth, jwt-auth, openid-connect and forward-auth plugins that you can place in front of MCP routes. Decide whether agents use per-agent consumers, delegated user tokens or service credentials, and test that revoking one agent does not affect others.

Rate limits for agent traffic

An agent can issue many tool calls in a short loop, so request rate limits protect upstream APIs and downstream systems. APISIX traffic control plugins can apply limits per consumer or per route. Ask how each limit counts requests in your deployment, especially when several gateway nodes share state, and set limits that match the tools an agent is allowed to call.

Checks before you rely on either plugin

Before any MCP design goes forward, confirm three things in your target APISIX release: whether the plugin is present, what specifications and transports it supports, and whether its authentication and logging hooks behave as your controls require. Run a test client through the full path and record the results. Ask your APISIX provider to put these checks in writing as part of the scope.

Which MCP path fits your situation

The mcp-bridge plugin connects MCP clients over SSE to a stdio MCP server that APISIX launches itself. The project lists it as deprecated and says it will be removed in a future release, so it suits a short evaluation or a test of how an existing setup behaves. It should not become the foundation of a production agent gateway. Read the mcp-bridge plugin documentation for the current status before you spend time on configuration.

Ownership: The stdio server runs on the gateway host, so your team owns its process lifecycle, dependencies, restarts and resource limits alongside the gateway.
Upgrade risk: Configuration you build now will need replacing when the plugin is removed, and the removal will follow the project's schedule.
Replacement path: Confirm with the project which successor it recommends before designing around this plugin, since the deprecation notice is the main guidance available today.
Blast radius: Launching a child process from the gateway widens what a gateway compromise can reach, which matters for segmented networks.

Before any evaluation, confirm the removal conditions in the version you intend to run and write down what the evaluation will not prove.

Setting up MCP routes in APISIX step by step

This sequence takes an MCP endpoint from an unverified APISIX install to a tested route that agent clients reach only with an authenticated identity and inside a rate limit. Each step ends with a check, so you can stop and roll back before the next change.

Confirm the APISIX version and plugin availability
Your platform team checks the release list on the APISIX downloads page and the plugin reference for the release you intend to run before writing any configuration. Confirm that the mcp-bridge and openapi-to-mcp plugins appear in that version's plugin list, and read the mcp-bridge deprecation notice, since the plugin is scheduled for removal in a future release. The step is done when you have written down the exact version, the plugin names present in it, and the deprecation status, and the team has agreed which of the two approaches it will build on.
Deploy a non-production APISIX instance
The platform team installs APISIX in a non-production environment in one of the three documented modes: traditional, decoupled or standalone. Traditional and decoupled modes depend on etcd, while standalone mode reads routes from a YAML or JSON file, which suits a small test rig with no etcd cluster. In traditional mode, client traffic arrives on port 9080 and the Admin API on port 9180, so confirm that only the intended networks can reach the Admin API. The step is done when the gateway starts, answers a basic request on the client port, and the Admin API rejects calls that do not carry your admin key.
Define the MCP upstream and route
The engineering team registers the upstream that serves the MCP endpoint and creates a route that matches the path agents will call. Decide now whether the backend is an MCP server that APISIX launches over stdio through mcp-bridge, which is deprecated, or an existing HTTP API exposed through openapi-to-mcp, and document the choice. Keep the route narrow, matching only the paths the agent needs, so that nothing else on the backend becomes reachable. The step is done when a request to the route reaches the backend and the response matches what the backend returns when called directly.
Add authentication for agent identities
The security team attaches an authentication plugin to the route so that each agent client has its own identity. key-auth or jwt-auth suit agents issued static or short-lived credentials, while openid-connect fits agents that obtain tokens from your identity provider through a client credentials flow. Create one consumer per agent or agent platform so that logs and limits can be attributed later. The step is done when a request without a credential is rejected, a request with a valid credential for one consumer succeeds, and a revoked or wrong credential is refused.
Apply rate limits per agent consumer
The platform team adds a rate-limiting plugin to the route, keyed by consumer, so one runaway agent cannot exhaust the backend for others. Agree the limits with the owners of the backend API, because the right values depend on how many calls the backend can absorb and how agents loop when a call fails. Confirm the limiter's counter storage and what happens to counts when APISIX runs more than one node. The step is done when a test consumer receives normal responses below the limit and a rejection status once it exceeds the limit, and the other consumers are unaffected.
Test the route with an MCP client
The engineering team connects a standard MCP client to the gateway route using a test consumer credential and runs the discovery and tool-call sequence the agent will use. Check that the tools listed match the set you approved, that a tool call returns the expected result, and that an unauthenticated client cannot list or call tools. Review the APISIX access logs for the consumer identity and the response codes. The step is done when the full sequence passes in the test environment and the logs show the expected consumer on every request.
Record the rollback point before promotion
Before any route moves toward production, the platform team exports the working configuration, whether from the Admin API or the standalone YAML file, and stores it in version control with the APISIX version and plugin list recorded alongside it. Document how to disable the MCP route without affecting other routes, and who has authority to do it. Confirm with your security team which of the chosen plugins are supported for your release before go-live. The step is done when the configuration can be restored to a known state from the stored copy, and the rollback steps have been run once in the test environment.

Why agent traffic needs authentication and rate limits at the gateway

Agent clients can issue many tool calls in a short time, and some act on behalf of a user, so the gateway needs to know which client is calling, what that client may reach, and how fast it may call. A single agent loop can fan out into dozens of requests against the same API, and a misconfigured or manipulated agent can do the same damage as a script without the review a human operator would apply. Treating each agent as a named client with its own credential and limits gives you a place to contain that behavior before it reaches the upstream service. In APISIX, that identity is modeled with a consumer. Each agent client, or each agent deployment if you prefer, becomes a consumer, and an authentication plugin such as key-auth or jwt-auth attaches the credential to it. Where agents act for a person, the openid-connect plugin can validate tokens issued by your identity provider, so the token carries the user's identity and the consumer carries the agent's. Rate limits and other traffic policies can then be applied per consumer. Confirm in your own environment which claims your identity provider puts into tokens and how your team maps them to consumers, because that mapping decides whether per-user limits are possible at all.

The gateway does not replace authorization inside the upstream API. APISIX can reject a request from an unknown client, enforce a request quota, or block a route the consumer should never use. It cannot know whether a particular customer record may be changed by the user the agent is acting for, because that decision depends on business data that lives behind the API. Plan for two layers: route-level and consumer-level controls at the gateway, and object-level checks in the service itself, with the identity forwarded so the service can make them. Before go-live, test that a valid agent credential cannot reach operations its owner was never meant to perform, and that a token for one user cannot retrieve another user's data through the same tool.

Questions teams ask before exposing APIs to agents

Is the APISIX mcp-bridge plugin safe to use now?

It works, but treat it as a bridge you plan to leave. The mcp-bridge plugin is deprecated and will be removed in a future release, so it is a poor foundation for a long-lived agent integration. It connects MCP clients over SSE to a stdio MCP server that APISIX launches itself, which means the server process, its dependencies and its credentials all run on the gateway host. If you already depend on it, plan a migration now: inventory which clients and servers use it, decide on the replacement pattern, and run both paths in parallel during cutover. Confirm the current deprecation notice and removal policy in the mcp-bridge plugin documentation before you set a date, because the project may change its timeline.

What does the client need to provide before an MCP rollout starts?

Three inputs decide how much work the rollout contains: an API inventory, an identity model and a test MCP client. The inventory lists each API you intend to expose, its owner, its operations, its data sensitivity and whether it already has an OpenAPI description. The identity model states which agents, users and service accounts may call which operations, and where that identity is issued (for example, an existing OpenID Connect provider). The test client is an MCP-capable client your team can point at a non-production route to verify tool discovery and calls. Without these, the work stalls in discovery, not in gateway configuration.

How long and how costly is an MCP gateway rollout?

Duration and cost follow from the number of APIs, the complexity of identity integration and the depth of testing. Each exposed API adds mapping, authorization rules and verification work, so a handful of internal endpoints differs greatly from a catalog of partner APIs. Identity integration with your existing provider is often the longest single item. Ask any provider for a quote built from a written scope that lists the APIs, the identity flows, the rate-limit policies and the test cases. Separate one-time costs (design, build, migration, test) from recurring costs (plugin upgrades, rule changes, monitoring, support). DeployOpen does not publish prices, and the quote follows from that scope.

Can our own team build MCP exposure on APISIX in-house?

Yes, if your team already runs APISIX or a comparable gateway and has engineers who can own the gateway configuration, identity integration and testing after go-live. The skills needed are gateway routing and plugin configuration, OpenAPI handling, OAuth or OpenID Connect design, and familiarity with MCP clients. Teams without one of these skills often buy a fixed-scope build and keep ownership of the result. A useful test is whether someone on your team can explain, without notes, how an agent's token is validated, how its calls are rate limited and how a change is rolled back.

What should we confirm in openapi-to-mcp before relying on it?

Confirm the behavior you need against the version you will run, not the plugin name. Check the current documentation for which OpenAPI versions it reads, how it maps operations to MCP tools, how it handles parameters, request bodies and authentication, and whether it forwards caller identity to the upstream API. Confirm how it behaves with errors and timeouts, and whether its output is stable when the OpenAPI document changes. Also confirm its support status and release notes in the APISIX plugin list. Test each of these in a non-production environment with your own specifications before committing.

How should agent clients authenticate and get rate limited?

Give each agent client its own identity and apply authorization at the gateway, not inside the upstream service alone. Typical options in APISIX include the openid-connect plugin for token introspection or JWT validation against your identity provider, and key-auth or jwt-auth for simpler cases. Bind each identity to a consumer with the operations it may call. For rate limits, set per-consumer limits so one agent that loops cannot exhaust a shared API. Confirm which limit plugin fits your traffic pattern and where the counters are stored in a multi-node deployment.

What breaks most often when agents call APIs through a gateway?

The most common failures are over-broad tool exposure, expired or unscoped tokens and unbounded retries. An agent may discover an operation that was never meant for it, or the API description may include fields the agent should not see. Token lifetimes that do not match the agent's session cause intermittent failures that look like tool errors. Retry loops amplify load on upstream services. Before go-live, test denial cases as thoroughly as success cases, log each tool call with its consumer identity, and review the log for operations that no agent should reach.

Security and operational risks for agent-facing APIs

Agent clients call your APIs without a person reviewing each request, so the gateway, its management plane and the tool calls themselves all become attack surface. The cards below cover where that surface sits and what to check before an agent reaches production APIs. Gateway controls limit what a request can reach, but they do not judge whether the model chose the right action.

Admin API exposure on port 9180

In traditional mode, APISIX serves client traffic on port 9080 and the Admin API on port 9180. Anyone who can reach the Admin API can change routes, plugins and consumers, so it should sit on an internal management network that agent clients never reach. Check that the listener is bound to a management interface, that firewall rules block it from client and agent subnets, and that access is restricted to the teams that operate the gateway.

Agent credentials in a secrets system

Each agent client needs a credential, such as an API key or a token issued through an identity provider. Store these in a dedicated secrets system rather than in agent configuration files, prompts or container images, and plan rotation before the first deployment. Ask who can read a credential, how revocation reaches the gateway, and whether a leaked agent key can be disabled without affecting other clients.

Least-privilege scopes per agent

Give each agent its own consumer identity and allow only the routes and MCP tools that its task requires. A reporting agent that reads orders should not be able to call refund or user-management endpoints, even when both sit behind the same gateway. Review scopes whenever an agent gains a new tool, and test that a denied call returns a refusal at the gateway rather than reaching the upstream service.

Logging of tool calls

Record which agent identity called which route or tool, the request time, the response status and the upstream that handled it. Gateway access logs show what was called, but they seldom show why, so keep the model's tool invocation trace in the agent platform and correlate the two by request ID. Confirm retention periods with your compliance owner and check that request bodies containing personal data are masked before they reach shared log storage.

Prompt-driven misuse of exposed endpoints

A prompt injected through a document, email or web page can steer an agent into calling an exposed endpoint with arguments the user never intended. Treat every tool argument as untrusted input, validate it at the upstream service, and keep destructive operations behind a human approval step or a separate credential. Rate limits and scopes cap the damage, but they do not identify a malicious instruction.

Gateway controls do not validate model behavior

APISIX enforces authentication, scopes, rate limits and request rules on the traffic it sees. It does not determine whether the model's chosen action was correct, safe or within business policy. Pair gateway controls with evaluation and testing of the agent itself, and document which risks sit with the gateway and which sit with the model, prompts and upstream services.

How DeployOpen scopes an MCP gateway project

A fixed scope agreed in writing comes before any build work on an MCP gateway. The scope fixes four things: the API inventory, the agent identity model, the plugin decision and the test plan. Each one changes the others, so they are settled together rather than in sequence. The inventory lists every REST or gRPC operation an agent may call, the upstream service behind it, and the data class each operation touches. The identity model names the agent clients, how each one authenticates to APISIX (for example, a consumer per agent with a key or JWT claim), which operations each consumer may call, and who approves a new agent.

The plugin decision is deliberately the last of these to be fixed. The mcp-bridge plugin is deprecated and slated for removal in a future release, and the openapi-to-mcp plugin needs to be checked against the OpenAPI definitions you actually run. DeployOpen plans a short verification run first: a test APISIX instance with one non-production route per candidate approach, confirming which MCP transport your agent clients speak, how tool definitions are generated, and how authentication and rate limits apply to tool calls. The written scope then names the chosen approach, or names a custom plugin or a service in front of APISIX if neither plugin fits.

The test plan is agreed up front and covers the agent-facing paths: unauthenticated and wrong-consumer calls, rate limit behavior per agent, logging of tool invocations, and failure handling when an upstream is down. All work is delivered in your own infrastructure, including the cloud accounts, data centers or restricted networks where APISIX and its etcd cluster run, so tool traffic and credentials stay under your control. Ask any partner to confirm which APISIX version and plugin list they verified against, and to confirm the removal status of mcp-bridge in the release you intend to run.

How DeployOpen works on this

DeployOpen plans, builds, documents and supports MCP gateway work on Apache APISIX inside infrastructure you control. Engagements start with a written scope that names which APIs agents may call, which clients are allowed, and which MCP plugin path is confirmed for your APISIX version.

How we scope

Inventory the internal APIs you want agents to call and classify each by data sensitivity and owner.
Confirm the APISIX version and whether the deprecated mcp-bridge or openapi-to-mcp path fits your target release.
Agree in writing the agent clients, authentication method, rate limits and exclusions before build work starts.

How we build

Configure routes, consumers and authentication for agent clients using APISIX plugins in your chosen deployment mode.
Apply per-consumer rate limits and request controls, and test them against realistic agent call patterns in a non-production environment.
Run security testing on the MCP endpoints, covering authentication bypass, tool-call abuse and exposed upstream services.

How we hand over

Deliver route, plugin and consumer configuration as files your team can version and review.
Document the tool exposure map, the decision record for the MCP plugin path and the steps to replace it when it is removed.
Walk your platform and security teams through operation, logging and rollback before the engagement closes.

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after handover.
Track APISIX release notes and flag plugin changes, including any removal of the mcp-bridge plugin, before your upgrade window.
Review new agent clients and tool exposures against the agreed scope and update the written record when scope changes.

Exposing APIs to AI agents through MCP with Apache APISIX