Portero

Portero is a self-hosted MCP gateway that sits between Claude Code and multiple MCP servers, unifying access, protecting privacy with data anonymization, and enabling controlled, auditable operations through 2FA approvals and policy-based permissions over a secure HTTPS endpoint.

How to use

You connect your MCP client to Portero’s public HTTPS endpoint to access multiple MCP servers as a single source. Portero anonymizes data as it travels to and from your MCPs, enforces permission policies for tool usage, and requires Telegram-based approvals for sensitive actions unless temporary grants bypass approval. When a tool requires approval, you receive a Telegram notification to approve or deny, and the gateway only forwards the response to Claude Code after your decision.

How to install

Prerequisites you need before starting are Node.js 20+ (LTS recommended) and a configured Telegram bot.

Follow these steps to set up Portero and connect your MCPs.

git clone <your-repo-url>
cd portero
npm install

Configure environment and MCPs

Set up the environment variables and MCP definitions shown in the following examples. These are essential for secure operation and for connecting to multiple MCP servers.

cp .env.example .env
# Edit .env with your settings

Connect Portero to Claude Code

Point Claude Code to Portero’s HTTP endpoint for MCP messages. Use the endpoint URL and include your bearer token in the request headers.

Configure MCP servers (example)

Define the MCPs Portero will manage. The following example shows two local MCP entries using npm-run commands to start server packages.

{
  "mcps": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
      "env": {}
    },
    {
      "name": "github",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  ]
}

Customize data anonymization and policies

Set up fake↔real data mappings to protect sensitive information and define who can perform which actions. You can configure bidirectional replacements and control case sensitivity. You also establish per-tool policies to allow, deny, or require approval for operations.

{
  "replacements": [
    {
      "fake": "John Doe",
      "real": "${REAL_NAME}",
      "bidirectional": true
    },
    {
      "fake": "john@example.com",
      "real": "${REAL_EMAIL}",
      "bidirectional": true,
      "caseSensitive": false
    }
  ]
}

Security basics

Use a strong bearer token, enable SSL in production, restrict access to the gateway port, and ensure only your admin Telegram chat can issue approvals.

BEARER_TOKEN=$(openssl rand -hex 32)
# Use TLS in production; consider Let's Encrypt or a reverse proxy

Starting the gateway

Start Portero in development mode for hot reloading, or build for production and run the built artifact.

# Development mode (hot reload)
npm run dev

# Production mode
npm run build
npm start

Troubleshooting

If the gateway won’t start, verify the Node.js version, ensure the .env file exists with required variables, and inspect logs. If MCP connections fail, confirm MCP commands and environment variables are correct. If the Telegram bot does not respond, check the bot token, admin chat ID, and that the bot is started.

Test the health endpoint and connectivity from Claude Code with a simple curl request.

curl -X POST https://localhost:8443/health

Available tools

anonymization

Replace real user data with fake values in requests and responses to protect privacy.

policyEngine

Evaluate tool usage against configured policies to determine allow, deny, or require-approval results.

twoFA

Coordinate two-factor approvals via Telegram to authorize sensitive actions.

auditTrail

Record grants, approvals, and actions for auditing and compliance.

mcpAggregation

Aggregate several MCP sources into a single unified endpoint.

remoteAccess

Serve MCP endpoints over HTTPS for access from anywhere.