Skip to main content

Using Private npm Packages in Hosted Servers

Organizations often maintain internal npm packages for shared utilities, proprietary integrations, or security-sensitive code. When hosting an MCP server that depends on private npm packages, you must configure registry authentication to allow the server to install dependencies during startup.

Authentication Approach​

npm supports authentication through environment variables prefixed with npm_config_. When deploying a hosted server that requires private packages, you configure these variables in the MCP connector settings.

Configuration Steps​

1. Identify Required Credentials​

Determine what authentication your private registry requires:

  • npm Enterprise or GitHub Packages: Authentication token
  • JFrog Artifactory: Token or username/password
  • Azure Artifacts: Personal access token
  • Custom registry: Check registry documentation

2. Set Args and Environment Variables​

When creating or editing your hosted MCP connector, add the appropriate npm_config_ environment variables:

For npm Enterprise or GitHub Packages​

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@myorg/private-mcp-server"],
      "env": {
        "npm_config_registry": "https://npm.pkg.github.com",
        "npm_config_//npm.pkg.github.com/:_authToken": "<github-token>"
      }
    }
  }
}

For Scoped Packages with Custom Registry​

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "-y",
        "--@myorg:registry=https://registry.mycompany.com",
        "@myorg/private-mcp-server"
      ],
      "env": {
        "npm_config_//registry.mycompany.com/:_authToken": "<auth-token>"
      }
    }
  }
}

For Multiple Registries​

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": [
        "-y",
        "--@myorg:registry=https://registry.mycompany.com",
        "--@partner:registry=https://npm.partner.com",
        "@myorg/private-mcp-server"
      ],
      "env": {
        "npm_config_//registry.mycompany.com/:_authToken": "<company-token>",
        "npm_config_//npm.partner.com/:_authToken": "<partner-token>"
      }
    }
  }
}

Security Considerations

  1. Token Permissions: Use tokens with minimal required permissions (read-only package access)
  2. Token Rotation: Establish a rotation schedule for shared tokens
  3. Encryption: All environment variables are encrypted at rest by MintMCP
  4. Least Privilege: Prefer scoped package authentication over global registry credentials

Common Registry Configurations​

GitHub Packages​

{
  "command": "npx",
  "args": [
    "-y",
    "--@myorg:registry=https://npm.pkg.github.com",
    "@myorg/private-mcp-server"
  ],
  "env": {
    "npm_config_//npm.pkg.github.com/:_authToken": "<github-pat>"
  }
}

Required GitHub token scopes: read:packages

Azure Artifacts​

{
  "command": "npx",
  "args": [
    "-y",
    "--@myorg:registry=https://pkgs.dev.azure.com/myorg/_packaging/myfeed/npm/registry/",
    "@myorg/private-mcp-server"
  ],
  "env": {
    "npm_config_//pkgs.dev.azure.com/myorg/_packaging/myfeed/npm/registry/:_authToken": "<azure-pat>"
  }
}

Required Azure DevOps token scopes: Packaging (read)

JFrog Artifactory​

{
  "command": "npx",
  "args": [
    "-y",
    "--@myorg:registry=https://mycompany.jfrog.io/artifactory/api/npm/npm-local/",
    "@myorg/private-mcp-server"
  ],
  "env": {
    "npm_config_//mycompany.jfrog.io/artifactory/api/npm/npm-local/:_authToken": "<artifactory-token>"
  }
}

Troubleshooting​

Server fails to start with 401, 404, or invalid token/password errors​

  • Verify the registry URL is correct
  • Confirm the package name and scope match your registry configuration
  • Check that the token has read access to the package

Authentication fails​

  • Ensure the npm_config_ prefix is correct for auth tokens
  • Verify token is not expired
  • Check that the registry path in the auth token variable matches exactly (including trailing slashes)
  • For scoped packages, ensure the --@scope:registry argument is passed in the args array

Next Steps​