# 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.

```json
{
  "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.

```toml
[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.

```toml
[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.

## 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.

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

```sh
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`.