TEUS MCP Proxy

teus-mcp-proxy is a local stdio bridge for TEUS MCP. It exchanges your TEUS email and password for a short-lived JWT, keeps that token only in the proxy process memory, refreshes it before expiry, and forwards MCP JSON-RPC to TEUS over HTTPS.

The TEUS MCP endpoint is currently an alpha feature and accepts only users with the TEUS ADMIN or ROOT authority. Accounts that require two-factor authentication cannot use this password-only proxy yet.

Client configuration

Set these environment variables in the MCP client configuration. Do not put the password in a committed configuration file.

{
  "mcpServers": {
    "teus": {
      "command": "npx",
      "args": ["-y", "--package=github:d1ys3nk0/teus-mcp-proxy", "teus-mcp-proxy"],
      "env": {
        "TEUS_HOST": "https://app.teus.pro",
        "TEUS_USER": "email@example.com",
        "TEUS_PASS": "your-password"
      }
    }
  }
}

Without an explicit Git ref, npx uses the repository's default branch.

Codex: GitHub default branch

Add this to ~/.codex/config.toml. Keep the credentials in this local file; do not commit them.

[mcp_servers.teus]
command = "npx"
args = ["-y", "--package=github:d1ys3nk0/teus-mcp-proxy", "teus-mcp-proxy"]
env_vars = ["TEUS_HOST", "TEUS_USER", "TEUS_PASS"]
startup_timeout_sec = 30

[mcp_servers.teus.env]
TEUS_HOST = "https://app.teus.pro"
TEUS_USER = "email@example.com"
TEUS_PASS = "your-password"

Codex: local checkout

Use this while developing the proxy locally. Replace the package path with the absolute path to your checkout.

[mcp_servers.teus]
command = "npx"
args = ["-y", "--package=file:/absolute/path/to/teus-mcp-proxy", "teus-mcp-proxy"]
env_vars = ["TEUS_HOST", "TEUS_USER", "TEUS_PASS"]
startup_timeout_sec = 30

[mcp_servers.teus.env]
TEUS_HOST = "https://app.teus.pro"
TEUS_USER = "email@example.com"
TEUS_PASS = "your-password"

TEUS_HOST must be the TEUS origin; the proxy always sends MCP requests to its /mcp endpoint. HTTPS is required, except for http://localhost, http://127.0.0.1, or http://[::1] during local development. URLs containing credentials, query parameters, or fragments are rejected.

Related MCP server: Uno MCP Stdio

Security and behavior

• Credentials and JWTs are never written to stdout, stderr, files, or logs.

• The JWT cache is memory-only and disappears when the proxy exits.

• The proxy renews a token shortly before expiry and retries a request once after TEUS returns 401 or 403.

• Network failures and TEUS 5xx responses are not retried automatically.

• Standard input and output use JSON-RPC-over-stdio; diagnostics use stderr only.

Development

Requires Node.js 22 or newer.

Live MCP smoke test

The smoke test authenticates using TEUS_HOST, TEUS_USER, and TEUS_PASS, then calls MCP initialize and tools/list. It prints only server metadata and the discovered tool count.

export TEUS_HOST="https://app.teus.pro"
export TEUS_USER="email@example.com"
export TEUS_PASS="your-password"
npm run smoke

npm test
npm run check
npm pack --dry-run

This project is intentionally dependency-free and is not published to npm. It is executed directly from the versioned GitHub repository through npx.