Deploxy Quick Start

Deploxy is a REAL proxy for deploying Stdio MCP server to serverless platform.

What this guide covers

• Deploying your Stdio MCP Server to NPM package with Deploxy.
• Transforming it into a secure, private MCP server.
• Keeping your source code safe while providing users with a lightweight proxy package to install.

Deployment Steps

Step 1: Clone this repository

git clone https://github.com/deploxy/quick-start.git
cd quick-start

Step 2: Configure NPM Publishing

Before you begin, you must have a .npmrc file in your project root that is configured for publishing packages to NPM.

@${YOUR_NPM_SCOPE}:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${YOUR_NPM_TOKEN}

Important: Your NPM token should never be committed to version control. It is best practice to load it from an environment variable like NPM_TOKEN.

Step 3: Prepare Your Project

First, ensure your project is ready to be published as a standard NPM package.

1. Configure package.json: Make sure your package.json has the required name, version, bin, and files properties set correctly.
2. Build Your Project: Install dependencies and run your build script.

   npm install
   npm run build

Step 4: Check your npm package

To understand the problem Deploxy solves, let's first publish the package the traditional way.

npm publish --access public

Now, go to your package's page on NPM (https://www.npmjs.com/package/YOUR_PACKAGE_NAME) and click on the "Code" tab. You will see that all your built code from the dist directory is publicly visible.

Important: This step is for this quick start demonstration only. In a real production, you will skip this step entirely.

Step 5: Create and Configure .deploxy.json

1. Create the file

   You have two options to create the .deploxy.json file.

   Option 1: Use the CLI

   Run the following command in your project root:

   npx @deploxy/cli init

   Option 2: Use the Dashboard

   Go to the Deploy new project to create a new project, then copy the generated JSON configuration into a .deploxy.json file in your project root.

2. Add your Auth Token: Open the file and add your authToken. If you don't have one, you can get it from the Tokens page.

   {
     "authToken": "your-auth-token-here",
     "defaultDeployRegion": "us-east-1",
     "stdioArgsIndex": "--args",
     "mcpPath": "/mcp",
     "packageType": "js"
     "injectedEnv": {},
   }

Step 6: Deploy with Deploxy

Now, instead of npm publish, run the deploy command.

Note: If you completed Step 4 and published a version to NPM, you must increment the version in your package.json before running deploy. Both NPM and Deploxy require a new version for each deployment.

npx @deploxy/cli deploy

You can monitor the deployment status on the Deploxy Dashboard.

Once deployment is complete, check your package page on NPM again. You will see that the code has been replaced with the Deploxy proxy client, which looks like this:

import { spawn } from "child_process";
import { configs } from "./configs.js";
import { parseConfigs } from "./lib.js";
function main() {
  const options = parseConfigs(configs);
  const mcp = spawn("npx", ["-y", "@deploxy/proxy@latest", ...options], {
    stdio: "inherit",
  });
  mcp.stdout?.on("data", (data) => {
    console.log(data.toString());
  });
  mcp.stderr?.on("data", (data) => {
    console.error(data.toString());
  });
  mcp.on("error", (error) => {
    console.error("MCP Proxy Error:");
    console.error(error);
    process.exit(1);
  });
  mcp.on("exit", process.exit);
}
main();

That's it! Your package is now deployed with Deploxy, keeping your source code private while providing a secure proxy for your users.

---

How It Works: The Deploxy Magic

When you deploy with Deploxy, you're not just publishing a package; you're creating a secure, private backend for your MCP server.

The code that end-users download and run via npx is a lightweight proxy client. This proxy client takes user requests (like a ToolCall) and streams them to your actual MCP server, which is running securely in the serverless cloud. This architecture allows you to focus on your core business logic without worrying about exposing sensitive information. You'll understand immediately once you inspect your published package on NPM after deployment.

Understanding the .deploxy.json properties

• authToken: This is the token required to authenticate and deploy your package to Deploxy.

• defaultDeployRegion: This is the default AWS region where your MCP server will run if the end-user does not specify a particular region. To give your end-users the fastest experience, they can specify a region using the --region flag when they run your package (npx -y your-pkg --region us-east-1). If the flag is omitted, this default region is used.

  With the Deploxy Pro plan, the --region parameter is not needed. Requests are automatically routed to the nearest region for the end-user.

• stdioArgsIndex: This option specifies the arguments that are passed directly to your MCP server. For example, when an end-user runs npx -y your-pkg --args user-api-key, your server can access user-api-key from process.argv.

• injectedEnv: This is an object of environment variables that are accessible only within your MCP server (e.g., process.env.DATABASE_URL). These are completely hidden from the end-user because they only interact with the proxy client, not your secure server code.

• mcpPath and packageType: You generally don't need to change these.

Security Warning: The .deploxy.json file contains your sensitive authToken. Never commit this file to a public repository. Ensure it is listed in your .gitignore file.