--- title: "Add Remote MCP Server with OAuth to Your Existing API" description: "Learn how to add a Model Context Protocol (MCP) server with OAuth authentication to your existing API in Zuplo, making it accessible to AI agents while maintaining enterprise-grade security." canonicalUrl: "https://zuplo.com/blog/2025/08/06/building-secure-mcp-servers-with-oauth" pageType: "blog" date: "2025-08-06" authors: "martyn" tags: "Model Context Protocol" image: "https://zuplo.com/og?text=Add%20Remote%20MCP%20Server%20with%20OAuth%20to%20Your%20Existing%20API" --- 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](https://portal.zuplo.com/signup) 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](https://auth0.com), but Zuplo supports any OAuth 2.0 compliant provider like [Okta](https://okta.com), [Clerk](https://clerk.com), [Supabase](https://supabase.com), [AWS Cognito](https://aws.amazon.com/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: ```bash 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](https://zuplo.com/examples/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](/media/posts/2025-08-06-building-secure-mcp-servers-with-oauth/openapi-import.png) 1. Create a new **empty** Zuplo project 2. Select the `routes.oas.json` from the _Code_ tab 3. Click on **Import OpenAPI** 4. Upload your OpenAPI JSON/YAML file 5. 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: 1. Go to your project's **Code** tab 2. In the `config` folder, create a new OpenAPI Spec and call it `mcp.oas.json` 3. **Add a new Route** to the file 4. Set the path to `/mcp` and method to `POST` 5. Select **MCP Server** as the Request Handler and set the OpenAPI Files dropdown to `./config/routes.oas.json` 6. Click on **Save** to deploy your changes ![Adding a new route in the Zuplo portal](/media/posts/2025-08-06-building-secure-mcp-servers-with-oauth/new-mcp-route.png) 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: ```json "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](https://auth0.com), 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](https://zuplo.com/docs/articles/configuring-auth0-for-mcp-auth) guide. The key configuration steps for Auth0 are: 1. Create an Auth0 API with your MCP server URL as the identifier 2. Enable Dynamic Client Registration 3. Configure a connection and promote it to domain level 4. 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: 1. In the Zuplo portal, go to your `/mcp` route 2. In the **Policies** section, click **Add Policy** in the **Request** section 3. Select **Auth0 JWT Auth** from the policy list (or whichever JWT Auth policy matches your provider of choice) ![JWT Policies Selection](/media/posts/2025-08-06-building-secure-mcp-servers-with-oauth/jwt-policies.png) 4. Configure the OAuth policy with your provider details: ![OAuth policy configuration form](/media/posts/2025-08-06-building-secure-mcp-servers-with-oauth/auth0-policy.png) For Auth0, the configuration looks like: ```json { "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: 1. In your project, open the `modules/zuplo.runtime.ts` file (create it if it doesn't exist using the _Empty Module_ option) 2. Add the plugin configuration: ```typescript 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](https://zuplo.com/docs/programmable-api/oauth-protected-resource-plugin) 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: 1. Click **Save** in the Zuplo portal 2. Wait for the deployment to complete (just a few seconds) 3. 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: ```bash npx @modelcontextprotocol/inspector ``` ![MCP Inspector interface](/media/posts/2025-08-06-building-secure-mcp-servers-with-oauth/mcp-inspector.png) To connect to your secure MCP server: 1. Set **Transport Type** to "Streamable HTTP" 2. Set **URL** to your MCP endpoint: `https://your-gateway.zuplo.dev/mcp` 3. Click **Open Auth Settings** to configure OAuth 4. Use the **Guided OAuth Flow** for step-by-step debugging 5. Complete the OAuth flow by logging in through your provider 6. Click **Connect** ![MCP Inspector showing successful connection with available tools](/media/posts/2025-08-06-building-secure-mcp-servers-with-oauth/mcp-inspector-tools.png) 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](https://zuplo.com/docs/policies/rate-limit-inbound) 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](https://zuplo.com/docs/policies/prompt-injection-outbound): Detects and blocks potential prompt poisoning attempts from making it further downstream where more harm could be caused. - [Secret Masking](https://zuplo.com/docs/policies/secret-masking-outbound): 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: 1. **Add More Endpoints**: Gradually expose more of your API endpoints as MCP tools based on AI agent usage patterns 2. **Create a production deployment**: In this example, testing has been done with the [Working Copy](https://zuplo.com/docs/articles/environments) version of the MCP Server. Once you are happy with the setup, [deploy a Production environment](https://zuplo.com/docs/articles/environments) for consumers to use. 3. **Monitor Usage**: Use Zuplo's analytics to understand which tools are most popular with AI agents 4. **Implement OAuth Scopes**: Use OAuth scopes to control which tools different types of users can access 5. **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](https://zuplo.com/examples/remote-mcp-server-with-oauth) or dive deeper into the [MCP Server documentation](https://zuplo.com/docs/mcp-server/introduction) for advanced configuration options.