Add Remote MCP Server with OAuth to Your Existing API

You've built an API and now you want to make it accessible to AI agents and LLM-powered applications.

While local MCP servers are straightforward, remote MCP servers require proper authentication, security, and hosting infrastructure. As a developer, it sure is nice to be able to add MCP capabilities to existing APIs without rebuilding everything from scratch.

In this article, we'll show you how to transform your existing API in Zuplo into a secure, remote MCP server with OAuth authentication in just a few steps, allowing API endpoints to become discoverable tools that AI agents can use while maintaining the right level of security.

What is MCP and Why OAuth Matters#

Model Context Protocol (MCP) acts as a bridge between AI systems (like Claude Desktop, Cursor, or custom AI agents) and external resources such as APIs.

For remote MCP servers, the security protocol most favored by clients and the MCP team is OAuth. This means that you get the additional benefits of:

User Identity: OAuth ensures that API calls are made on behalf of authenticated users
Scoped Access: Fine-grained control over what resources AI agents can access
Token-based Security: No need to share long-lived credentials with AI systems
Audit Trail: Complete visibility into which users and agents are accessing your APIs (which is useful for creating better security patterns later on)

Many MCP consumers, including Claude Desktop, require OAuth authentication for remote MCP servers, making it more of a dealbreaker than just a security best practice.

Prerequisites#

Before we begin, you'll need:

A Zuplo account (Sign up for free if you don't have one)
An existing API in Zuplo (or an OpenAPI specification for your API to import)
An OAuth provider (This guide uses Auth0, but Zuplo supports any OAuth 2.0 compliant provider like Okta, Clerk, Supabase, AWS Cognito, etc.)
Basic familiarity with APIs and OpenAPI specifications

Optional: Using Local Development#

This article walks you through the setup of an OAuth protected MCP Server using the Zuplo Portal. If you prefer to work locally in your IDE then you can get a full, configurable, example project by running:

npx create-zuplo-api@latest --example remote-mcp-server-with-oauth

The full walkthrough for this local development example can be found on the example page for Remote MCP Server with OAuth

Step 1: Ensure Your API is Ready#

If you already have an API running in Zuplo with proper OpenAPI documentation, you can skip to Step 2. Good for you.

If you don't have an API in Zuplo yet, the fastest way to get started is to import your existing OpenAPI specification:

Screenshot showing the file import dialog with OpenAPI options

Create a new empty Zuplo project
Select the routes.oas.json from the Code tab
Click on Import OpenAPI
Upload your OpenAPI JSON/YAML file
Zuplo will automatically create routes and handlers based on your specification

The key requirement is that your API has proper OpenAPI documentation with clear summaries and descriptions for each endpoint. These descriptions will help AI agents understand when and how to use each tool.

Step 2: Adding the MCP Server Handler#

Now we'll add an MCP server endpoint to your existing API. This single endpoint will expose your chosen API routes as discoverable tools for AI agents.

Adding the MCP Route#

In the Zuplo portal:

Go to your project's Code tab
In the config folder, create a new OpenAPI Spec and call it mcp.oas.json
Add a new Route to the file
Set the path to /mcp and method to POST
Select MCP Server as the Request Handler and set the OpenAPI Files dropdown to ./config/routes.oas.json
Click on Save to deploy your changes

Adding a new route in the Zuplo portal

You now have a fresh MCP server connected to your API that uses the endpoints defined in routes.oas.json. Currently, all endpoints will be exposed as tools.

Defining specific routes as MCP tools#

If you want to be specific about which routes are exposed as tools, you can edit the mcp.oas.json file and define each route explicitly, like so:

"paths": {
  "/mcp": {
    "post": {
      "x-zuplo-route": {
        "handler": {
          "export": "mcpServerHandler",
          "module": "$import(@zuplo/runtime)",
          "options": {
            "openApiTools": [
              {
                "path": "/todos",
                "method": "GET",
                "name": "get_todos",
                "description": "Gets todos from the backend"
              },
              {
                "operationId": "get_todos_by_priority",
                "method": "GET"
              }
            ]
          }
        }
      }
    }
  }
}

Step 3: Adding OAuth Authentication#

Next, we'll secure your MCP server with OAuth authentication. This ensures only authorized users and AI agents can access your API tools.

Setting Up Your OAuth Provider#

For this example, we'll use Auth0, but Zuplo supports any OAuth 2.0 provider.

If you already have your provider in place, you can use the configuration for them. If not, you can follow our Setting up Auth0 as an Authentication Server for MCP OAuth Authentication guide.

The key configuration steps for Auth0 are:

Create an Auth0 API with your MCP server URL as the identifier
Enable Dynamic Client Registration
Configure a connection and promote it to domain level
Set up a default audience

Adding OAuth Policy to Your MCP Route#

Once your OAuth provider is configured, you'll add an OAuth policy to your MCP route:

In the Zuplo portal, go to your /mcp route
In the Policies section, click Add Policy in the Request section
Select Auth0 JWT Auth from the policy list (or whichever JWT Auth policy matches your provider of choice)

JWT Policies Selection

Configure the OAuth policy with your provider details:

OAuth policy configuration form

For Auth0, the configuration looks like:

{
  "auth0Domain": "your-domain.us.auth0.com",
  "audience": "https://your-gateway.zuplo.dev/mcp",
  "oAuthResourceMetadataEnabled": true
}

The critical setting is "oAuthResourceMetadataEnabled": true - this enables the OAuth metadata endpoints that MCP clients need for authentication.

Adding the OAuth Protected Resource Plugin#

Finally, add the OAuth Protected Resource Plugin to enable OAuth discovery on your gateway:

In your project, open the modules/zuplo.runtime.ts file (create it if it doesn't exist using the Empty Module option)
Add the plugin configuration:

import {
  RuntimeExtensions,
  OAuthProtectedResourcePlugin,
} from "@zuplo/runtime";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addPlugin(
    new OAuthProtectedResourcePlugin({
      authorizationServers: ["https://your-domain.us.auth0.com"],
      resourceName: "My MCP Server",
    }),
  );
}

This plugin populates the .well-known routes for the MCP server authentication metadata discovery. This enables MCP clients to automatically discover the authorization issuer endpoint. See the OAuth Protected Resource Plugin docs for more details on this runtime plugin.

Step 4: Testing Your MCP Server#

Now let's test that your MCP server is working correctly with OAuth authentication.

Deploy Your Changes#

First, make sure to deploy your changes:

Click Save in the Zuplo portal
Wait for the deployment to complete (just a few seconds)
Note your gateway URL from the Deployment URLs dropdown in your project (to begin with you can use the Working Copy URL for testing, but we do not recommend this for Production)

Note: Working Copy is for development. To begin with you can use the Working Copy URL for testing, but we do not recommend this for Production.

Testing with MCP Inspector#

The MCP Inspector is the best tool for testing that MCP servers are set up correctly:

npx @modelcontextprotocol/inspector

MCP Inspector interface

To connect to your secure MCP server:

Set Transport Type to "Streamable HTTP"
Set URL to your MCP endpoint: https://your-gateway.zuplo.dev/mcp
Click Open Auth Settings to configure OAuth
Use the Guided OAuth Flow for step-by-step debugging
Complete the OAuth flow by logging in through your provider
Click Connect

MCP Inspector showing successful connection with available tools

If everything is configured correctly, you'll see your API endpoints listed as available tools that can be called by AI agents. You can test each tool directly in the Inspector to verify they work as expected.

Step 5: Production Security Considerations#

For production deployments, consider adding these security policies to your MCP route:

Rate Limiting#

Protect your MCP server from abuse by adding a rate limiting policy on your inbound requests. This prevents AI agents from overwhelming your API with too many requests.

AI Security Policies#

Zuplo offers specialized security policies for AI workloads:

Prompt Injection Detection: Detects and blocks potential prompt poisoning attempts from making it further downstream where more harm could be caused.
Secret Masking: Automatically redacts sensitive information from API responses. This policy can be configured to match multiple patterns for any kind of data you want to redact from responses.

These policies are especially important when your API handles sensitive data that could be exposed through AI agent interactions.

Next Steps#

Now that your API is MCP-enabled, here are some ways to expand its capabilities:

Add More Endpoints: Gradually expose more of your API endpoints as MCP tools based on AI agent usage patterns
Create a production deployment: In this example, testing has been done with the Working Copy version of the MCP Server. Once you are happy with the setup, deploy a Production environment for consumers to use.
Monitor Usage: Use Zuplo's analytics to understand which tools are most popular with AI agents
Implement OAuth Scopes: Use OAuth scopes to control which tools different types of users can access
Enhance Documentation: Improve your OpenAPI descriptions to help AI agents better understand when to use each tool. This is especially important when you have many tools available, some of which may perform similar operations

Conclusion#

Adding MCP server capabilities to your existing API is straightforward with Zuplo. In just a few steps, you've:

✅ Transformed your API endpoints into AI-accessible tools
✅ Secured access with OAuth authentication
✅ Deployed a remote MCP server
✅ Enabled your API to work with AI agents and LLM applications

Your API is now ready for the AI-powered future. AI agents can discover, understand, and interact with your services through the standardized MCP protocol while maintaining the security and control you need.

Ready to try it yourself? Check out our complete example project or dive deeper into the MCP Server Handler documentation for advanced configuration options.