Skip to main content

STDIO Server Packages

Learn how to install and manage STDIO-based MCP server packages with MCP Gatekeeper.

Overview​

MCP Gatekeeper provides a streamlined interface for installing and managing STDIO-based MCP server packages from the npm registry. The package manager handles installation, dependency resolution, and automatic wrapper injection for metrics collection.

Note: For HTTP-based MCP servers, see HTTP Servers.

Installing Packages​

From the Web UI​

  1. Navigate to the Stdio Servers page
  2. Click "Install from npm"
  3. Enter the package name (e.g., @modelcontextprotocol/server-filesystem)
  4. Optionally specify a version (defaults to latest)
  5. Click Install

The package will be downloaded and installed automatically.

Package Sources​

MCP Gatekeeper currently supports:

  • npm registry: Public npm packages
  • Scoped packages: Packages like @org/package-name
  • Specific versions: Install a particular version
# Filesystem access
@modelcontextprotocol/server-filesystem

# GitHub integration
@modelcontextprotocol/server-github

# Web automation
@modelcontextprotocol/server-puppeteer

# Database access
@modelcontextprotocol/server-postgres

# Brave Search
@modelcontextprotocol/server-brave-search

# Google Maps
@modelcontextprotocol/server-google-maps

How It Works​

Installation Process​

  1. Validation: Package name and version validated
  2. npm install: Package installed using npm
  3. Dependency Resolution: npm handles dependencies
  4. Binary Detection: Main entry point identified
  5. Wrapper Injection: STDIO wrapper added for metrics
  6. Database Record: Package info stored in database
  7. Notification: Frontend receives success notification

Installation Directory​

Packages are installed in:

~/.mcp-gatekeeper/packages/
└── node_modules/
    └── @modelcontextprotocol/
        └── server-filesystem/

STDIO Wrapper​

The package manager automatically wraps MCP server binaries with a metrics collection wrapper:

// wrapper_template.js
// Intercepts STDIO communication
// Collects metrics transparently
// Forwards messages to actual server

This enables zero-code metrics collection without modifying the original package.

Managing Packages​

Viewing Installed Packages​

The Stdio Servers page shows:

  • Package Name: Full package identifier
  • Version: Installed version
  • Install Date: When it was installed
  • Size: Package size on disk
  • Actions: View details, README, uninstall

Viewing Package Details​

Click on a package to view:

  • Package metadata: Name, version, description
  • Dependencies: Required packages
  • README: Package documentation
  • Entry point: Main executable file
  • Installation path: Where it's installed

Uninstalling Packages​

  1. Navigate to the Stdio Servers page
  2. Find the package you want to remove
  3. Click the Delete icon
  4. Confirm the deletion

Note: Uninstalling a package will also remove it from any agent configurations that reference it.

Troubleshooting​

Installation Fails​

Problem: Package installation fails

Solutions:

  1. Check internet connection
  2. Verify package name is correct
  3. Try installing without a version
  4. Check npm registry is accessible
  5. Review backend logs for errors

Package Not Found​

Problem: "Package not found" error

Solutions:

  1. Verify package exists on npm: npm view <package-name>
  2. Check for typos in package name
  3. Ensure package is publicly available

Permission Errors​

Problem: Permission denied during installation

Solutions:

  1. Check file permissions on ~/.mcp-gatekeeper/packages/
  2. Run with appropriate permissions
  3. Check disk space availability

Wrapper Not Working​

Problem: Metrics not being collected

Solutions:

  1. Verify app/templates/wrapper_template.js exists in backend
  2. Check server logs for wrapper errors
  3. Restart the MCP server
  4. Re-install the package

Advanced Usage​

Installing Specific Versions​

Package name: @modelcontextprotocol/server-filesystem
Version: 1.2.3

Installing from Git​

Currently not supported. Packages must be published to npm.

Custom Package Registry​

To use a private npm registry, configure:

# In apps/backend/.env
NPM_REGISTRY=https://your-registry.com/

Manual Installation​

For development/testing, you can manually install packages:

cd ~/.mcp-gatekeeper/packages
npm install <package-name>

Then manually add to the database or use the UI to "discover" it.

Package Requirements​

For a STDIO package to work with MCP Gatekeeper:

  1. MCP Protocol: Must implement MCP protocol
  2. STDIO Communication: Must use STDIO transport (not HTTP)
  3. npm Package: Must be installable via npm
  4. Executable: Must have a runnable entry point

For HTTP-based servers: Use the HTTP Servers feature instead.

Best Practices​

  1. Use Official Packages: Prefer @modelcontextprotocol/ scoped packages
  2. Specify Versions: Pin to specific versions for stability
  3. Review README: Check package documentation before installing
  4. Test Locally: Test packages before adding to agent configs
  5. Keep Updated: Regularly update packages for security fixes

Transport Types​

MCP Gatekeeper supports two transport types:

  1. STDIO Servers (this page) - Local packages installed via npm
  2. HTTP Servers - Remote servers accessed via HTTP/SSE

Both types provide the same monitoring and metrics capabilities.

Next Steps​