# Connect to MCP Gateway (agent one-shot)

Public instructions for agents with lab access (Bitwarden/`bws`, secret-gate, or SSH to konstant).  
**Never** put the API key value in chat, commits, or notes.

Live page: `https://mcp-gateway-konstant.hectorsanchez.eu/connect`  
Raw markdown: `https://mcp-gateway-konstant.hectorsanchez.eu/connect.md`

## What this is

Code-mode MCP gateway for **Google Workspace** (Gmail, Calendar, Drive, Docs, Sheets, Tasks) on konstant-server.

Meta-tools: `list_servers`, `search_tools`, `execute_code` (call `gws.*` inside code).

## Endpoints

| Purpose | URL |
|---------|-----|
| MCP | `https://mcp-gateway-konstant.hectorsanchez.eu/mcp` |
| Health | `https://mcp-gateway-konstant.hectorsanchez.eu/health` |
| This guide | `https://mcp-gateway-konstant.hectorsanchez.eu/connect` |

Auth on `/mcp`: `Authorization: Bearer <key>` **or** `?key=<key>` (ChatGPT).

## Secret

- Bitwarden Secrets Manager key name: **`MCP_GATEWAY_API_KEY`**
- Host file (fallback): `/srv/apps/mcp-gateway/shared/.env` on konstant (`MCP_GATEWAY_API_KEY=…`)

Do not echo the value into agent transcripts when avoidable; use it only to configure the client or a local env var.

## Retrieve the secret (first that works)

### A — `bws` (preferred)

```bash
export PATH="$HOME/.local/bin:$PATH"
source ~/.local/state/secret-gate/session.env 2>/dev/null || true
KEY=$(bws secret list -o json | python3 -c '
import json,sys
wanted="MCP_GATEWAY_API_KEY"
for s in json.load(sys.stdin):
    if s.get("key")==wanted:
        print(s.get("value",""))
        break
')
test -n "$KEY" && echo "got MCP_GATEWAY_API_KEY (len=${#KEY})"
```

### B — secret-gate if session cold

```bash
export PATH="$HOME/.local/bin:$PATH"
~/Documents/ubuntu-server-lab/runbooks/secret-gate.sh
# then retry A
```

Lab Bitwarden notes: `~/Documents/ubuntu-server-lab/runbooks/02-bitwarden.md`

### C — SSH fallback (konstant)

```bash
KEY=$(ssh konstant-ts 'sudo grep ^MCP_GATEWAY_API_KEY= /srv/apps/mcp-gateway/shared/.env | cut -d= -f2-')
test -n "$KEY" && echo "got key via ssh (len=${#KEY})"
```

### If Bitwarden secret missing

1. Read value via SSH (C) once.
2. Create/update SM secret named `MCP_GATEWAY_API_KEY` (agent may `bws secret create` placeholder; human pastes real value in Bitwarden UI if create is placeholder-only).
3. Prefer Bitwarden going forward—do not commit the value.

## Configure clients

### Cursor / Codex (Bearer)

Merge into Cursor MCP settings (or project `.cursor/mcp.json` if used):

```json
{
  "mcpServers": {
    "mcp-gateway": {
      "url": "https://mcp-gateway-konstant.hectorsanchez.eu/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_GATEWAY_API_KEY>"
      }
    }
  }
}
```

Example file in repo: `docs/cursor.mcp.example.json`.

### ChatGPT (Plus, web first)

1. Enable **Developer mode** (Settings → Security and login).
2. Plugins → **Create app**:
   - Name: `MCP Gateway`
   - Server URL: `https://mcp-gateway-konstant.hectorsanchez.eu/mcp?key=<MCP_GATEWAY_API_KEY>`
   - Authentication: **No Auth**
3. Connect; enable in a chat (+ → More → MCP Gateway).
4. Expect tools: `list_servers`, `search_tools`, `execute_code`.

## Smoke (must pass)

```bash
export MCP_BASE="https://mcp-gateway-konstant.hectorsanchez.eu"
# KEY from A/B/C above — do not paste into chat
curl -sS "$MCP_BASE/health"
curl -sS -X POST "$MCP_BASE/mcp" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"connect-smoke","version":"0.0.1"}}}'
```

Expect: initialize `instructions` mention `gws` / Google Workspace; then call tools / `execute_code`.

If public DNS fails on the agent host, use Tailscale:

```bash
curl -sS -H 'Host: mcp-gateway-konstant.hectorsanchez.eu' \
  https://konstant-server.tail64860f.ts.net/health
```

## After connect

1. `gws.auth_status({})` to confirm the authenticated account and granted scopes.
2. `search_tools({ query: "gmail", detail: "full" })` for schemas + code stubs.
3. Writes are gated server-side by `GWS_WRITE_ENABLED=1`.
4. If `/health` lists a `secrets` backend, `secrets_list`/`secrets_check`/`secrets_sets`
   expose secret metadata (never values) and `secrets_get` reveals one value with a
   mandatory `reason`; every call is audit-logged.

## References

| Ref | Where |
|-----|--------|
| Source repo | `https://github.com/Konstant-Ventures/mcp-gateway` (private) |
| Lab runbook | `~/Documents/ubuntu-server-lab/runbooks/11-mcp-gateway-konstant.md` |
| Bitwarden | `~/Documents/ubuntu-server-lab/runbooks/02-bitwarden.md` |
| ChatGPT detail | repo `docs/chatgpt.md` |