Skip to content

Commit bf761c5

Browse files
kevalmahajancrivetimihai
kevalmahajan
and
crivetimihai
authored
Redesigned wrapper functionality (#780)
* updated wrapper functionality Signed-off-by: Keval Mahajan <[email protected]> * resolved flake8 issues Signed-off-by: Keval Mahajan <[email protected]> * fixed stream doctest Signed-off-by: Keval Mahajan <[email protected]> * Fixed Test Cases Signed-off-by: Keval Mahajan <[email protected]> * added missing docstrings Signed-off-by: Keval Mahajan <[email protected]> * minor changes Signed-off-by: Keval Mahajan <[email protected]> * Rebase and test Signed-off-by: Mihai Criveti <[email protected]> --------- Signed-off-by: Keval Mahajan <[email protected]> Signed-off-by: Mihai Criveti <[email protected]> Co-authored-by: Mihai Criveti <[email protected]>
1 parent f3df539 commit bf761c5

25 files changed

+1068
-1420
lines changed

‎AGENTS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,5 +62,5 @@ MCP helpers
6262
## Security & Configuration Tips
6363
- Copy `.env.example` → `.env`; verify with `make check-env`. Never commit secrets.
6464
- Auth: set `JWT_SECRET_KEY`; export `MCPGATEWAY_BEARER_TOKEN` using the token utility for API calls.
65-
- Wrapper: set `MCP_SERVER_CATALOG_URLS` and `MCP_AUTH_TOKEN` when using `mcpgateway.wrapper`.
65+
- Wrapper: set `MCP_SERVER_URL` and `MCP_AUTH` when using `mcpgateway.wrapper`.
6666
- TLS: `make certs` → `make serve-ssl`. Prefer environment variables for config; see `README.md`.

‎CLAUDE.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,8 @@ python3 -m mcpgateway.translate \
5858
--stdio "uvx mcp-server-git" --port 9000
5959

6060
# Run the stdio wrapper for MCP clients
61-
export MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN
62-
export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID
61+
export MCP_AUTH=$MCPGATEWAY_BEARER_TOKEN
62+
export MCP_SERVER_URL=http://localhost:4444/servers/UUID/mcp
6363
python3 -m mcpgateway.wrapper
6464
```
6565

‎DEVELOPING.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,8 @@
55
```bash
66
# Gateway & auth
77
export MCP_GATEWAY_BASE_URL=http://localhost:4444
8-
export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1
9-
export MCP_AUTH_TOKEN="<your_bearer_token>"
8+
export MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp
9+
export MCP_AUTH="<your_bearer_token>"
1010
```
1111

1212
| Mode | Command | Notes |

‎README.md

Lines changed: 35 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -376,22 +376,32 @@ npx -y @modelcontextprotocol/inspector
376376
<summary><strong>🖧 Using the stdio wrapper (mcpgateway-wrapper)</strong></summary>
377377

378378
```bash
379-
export MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN
380-
export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1
379+
export MCP_AUTH=$MCPGATEWAY_BEARER_TOKEN
380+
export MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp
381381
python3 -m mcpgateway.wrapper # Ctrl-C to exit
382382
```
383383

384384
You can also run it with `uv` or inside Docker/Podman - see the *Containers* section above.
385385

386-
In MCP Inspector, define `MCP_AUTH_TOKEN` and `MCP_SERVER_CATALOG_URLS` env variables, and select `python3` as the Command, and `-m mcpgateway.wrapper` as Arguments.
386+
In MCP Inspector, define `MCP_AUTH` and `MCP_SERVER_URL` env variables, and select `python3` as the Command, and `-m mcpgateway.wrapper` as Arguments.
387387

388388
```bash
389389
echo $PWD/.venv/bin/python3 # Using the Python3 full path ensures you have a working venv
390-
export MCP_SERVER_CATALOG_URLS='http://localhost:4444/servers/UUID_OF_SERVER_1'
391-
export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
390+
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'
391+
export MCP_AUTH=${MCPGATEWAY_BEARER_TOKEN}
392392
npx -y @modelcontextprotocol/inspector
393393
```
394394

395+
or
396+
397+
Pass the url and auth as arguments (no need to set environment variables)
398+
```bash
399+
npx -y @modelcontextprotocol/inspector
400+
command as `python`
401+
Arguments as `-m mcpgateway.wrapper --url "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp" --auth "Bearer <your token>"`
402+
```
403+
404+
395405
When using a MCP Client such as Claude with stdio:
396406

397407
```json
@@ -401,8 +411,8 @@ When using a MCP Client such as Claude with stdio:
401411
"command": "python",
402412
"args": ["-m", "mcpgateway.wrapper"],
403413
"env": {
404-
"MCP_AUTH_TOKEN": "your-token-here",
405-
"MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1",
414+
"MCP_AUTH": "your-token-here",
415+
"MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1",
406416
"MCP_TOOL_CALL_TIMEOUT": "120"
407417
}
408418
}
@@ -591,14 +601,14 @@ The `mcpgateway.wrapper` lets you connect to the gateway over **stdio** while ke
591601
```bash
592602
# Set environment variables
593603
export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)
594-
export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
595-
export MCP_SERVER_CATALOG_URLS='http://localhost:4444/servers/UUID_OF_SERVER_1'
604+
export MCP_AUTH=${MCPGATEWAY_BEARER_TOKEN}
605+
export MCP_SERVER_URL='http://localhost:4444/servers/UUID_OF_SERVER_1/mcp'
596606
export MCP_TOOL_CALL_TIMEOUT=120
597607
export MCP_WRAPPER_LOG_LEVEL=DEBUG # or OFF to disable logging
598608

599609
docker run --rm -i \
600-
-e MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN \
601-
-e MCP_SERVER_CATALOG_URLS=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1 \
610+
-e MCP_AUTH=$MCPGATEWAY_BEARER_TOKEN \
611+
-e MCP_SERVER_URL=http://host.docker.internal:4444/servers/UUID_OF_SERVER_1/mcp \
602612
-e MCP_TOOL_CALL_TIMEOUT=120 \
603613
-e MCP_WRAPPER_LOG_LEVEL=DEBUG \
604614
ghcr.io/ibm/mcp-context-forge:0.5.0 \
@@ -615,8 +625,8 @@ Because the wrapper speaks JSON-RPC over stdin/stdout, you can interact with it
615625

616626
```bash
617627
# Start the MCP Gateway Wrapper
618-
export MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN}
619-
export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/YOUR_SERVER_UUID
628+
export MCP_AUTH=${MCPGATEWAY_BEARER_TOKEN}
629+
export MCP_SERVER_URL=http://localhost:4444/servers/YOUR_SERVER_UUID
620630
python3 -m mcpgateway.wrapper
621631
```
622632

@@ -667,8 +677,8 @@ python3 -m mcpgateway.wrapper
667677

668678
The `mcpgateway.wrapper` exposes everything your Gateway knows about over **stdio**, so any MCP client that *can't* (or *shouldn't*) open an authenticated SSE stream still gets full tool-calling power.
669679

670-
> **Remember** to substitute your real Gateway URL (and server ID) for `http://localhost:4444/servers/UUID_OF_SERVER_1`.
671-
> When inside Docker/Podman, that often becomes `http://host.docker.internal:4444/servers/UUID_OF_SERVER_1` (macOS/Windows) or the gateway container's hostname (Linux).
680+
> **Remember** to substitute your real Gateway URL (and server ID) for `http://localhost:4444/servers/UUID_OF_SERVER_1/mcp`.
681+
> When inside Docker/Podman, that often becomes `http://host.docker.internal:4444/servers/UUID_OF_SERVER_1/mcp` (macOS/Windows) or the gateway container's hostname (Linux).
672682
673683
---
674684

@@ -678,8 +688,8 @@ The `mcpgateway.wrapper` exposes everything your Gateway knows about over **stdi
678688
```bash
679689
docker run -i --rm \
680690
--network=host \
681-
-e MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1 \
682-
-e MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
691+
-e MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp \
692+
-e MCP_AUTH=${MCPGATEWAY_BEARER_TOKEN} \
683693
-e MCP_TOOL_CALL_TIMEOUT=120 \
684694
ghcr.io/ibm/mcp-context-forge:0.5.0 \
685695
python3 -m mcpgateway.wrapper
@@ -697,8 +707,8 @@ docker run -i --rm \
697707
pipx install --include-deps mcp-contextforge-gateway
698708

699709
# Run the stdio wrapper
700-
MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
701-
MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1 \
710+
MCP_AUTH=${MCPGATEWAY_BEARER_TOKEN} \
711+
MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp \
702712
python3 -m mcpgateway.wrapper
703713
# Alternatively with uv
704714
uv run --directory . -m mcpgateway.wrapper
@@ -713,8 +723,8 @@ uv run --directory . -m mcpgateway.wrapper
713723
"command": "python3",
714724
"args": ["-m", "mcpgateway.wrapper"],
715725
"env": {
716-
"MCP_AUTH_TOKEN": "<your-token>",
717-
"MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1",
726+
"MCP_AUTH": "<your-token>",
727+
"MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp",
718728
"MCP_TOOL_CALL_TIMEOUT": "120"
719729
}
720730
}
@@ -750,8 +760,8 @@ source ~/.venv/mcpgateway/bin/activate
750760
uv pip install mcp-contextforge-gateway
751761

752762
# Launch wrapper
753-
MCP_AUTH_TOKEN=${MCPGATEWAY_BEARER_TOKEN} \
754-
MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1 \
763+
MCP_AUTH=${MCPGATEWAY_BEARER_TOKEN} \
764+
MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp \
755765
uv run --directory . -m mcpgateway.wrapper # Use this just for testing, as the Client will run the uv command
756766
```
757767

@@ -770,8 +780,8 @@ uv run --directory . -m mcpgateway.wrapper # Use this just for testing, as the C
770780
"mcpgateway.wrapper"
771781
],
772782
"env": {
773-
"MCP_AUTH_TOKEN": "<your-token>",
774-
"MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1"
783+
"MCP_AUTH": "<your-token>",
784+
"MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp"
775785
}
776786
}
777787
}

‎docs/docs/overview/quick_start.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -207,8 +207,8 @@ npx -y @modelcontextprotocol/inspector
207207
## Connect via `mcpgateway-wrapper` (stdio)
208208

209209
```bash
210-
export MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN
211-
export MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1
210+
export MCP_AUTH=$MCPGATEWAY_BEARER_TOKEN
211+
export MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1/mcp
212212
python3 -m mcpgateway.wrapper # behaves as a local MCP stdio server - run from MCP client
213213
```
214214

@@ -221,8 +221,8 @@ Use this in GUI clients (Claude Desktop, Continue, etc.) that prefer stdio. Exam
221221
"command": "python3",
222222
"args": ["-m", "mcpgateway.wrapper"],
223223
"env": {
224-
"MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1",
225-
"MCP_AUTH_TOKEN": "<YOUR_JWT_TOKEN>",
224+
"MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1/mcp",
225+
"MCP_AUTH": "<YOUR_JWT_TOKEN>",
226226
"MCP_TOOL_CALL_TIMEOUT": "120"
227227
}
228228
}

‎docs/docs/testing/acceptance.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ graph TB
165165
| Feature | URL | Commands | Expected Result | Status | Notes |
166166
|---------|-----|----------|-----------------|--------|-------|
167167
| Install Package | `pip install mcp-contextforge-gateway` | Install for wrapper | Package installed | ☐ | If not already done |
168-
| Set Environment | `export MCP_SERVER_CATALOG_URLS="$GW_URL/servers/$TIME_SERVER_UUID" && export MCP_AUTH_TOKEN=$MCPGATEWAY_BEARER_TOKEN` | Configure wrapper | Environment set | ☐ | Point to virtual server |
168+
| Set Environment | `export MCP_SERVER_URL="$GW_URL/servers/$TIME_SERVER_UUID" && export MCP_AUTH=$MCPGATEWAY_BEARER_TOKEN` | Configure wrapper | Environment set | ☐ | Point to virtual server |
169169
| Test Wrapper Init | `echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \| python3 -m mcpgateway.wrapper 2>/dev/null \| jq` | Initialize via stdio | Returns capabilities with tools | ☐ | Stdio to HTTP bridge |
170170
| List Tools via Wrapper | `echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \| python3 -m mcpgateway.wrapper 2>/dev/null \| jq` | List tools via stdio | Returns tool list | ☐ | Wrapper functionality |
171171

@@ -183,8 +183,8 @@ graph TB
183183
"command": "python",
184184
"args": ["-m", "mcpgateway.wrapper"],
185185
"env": {
186-
"MCP_SERVER_CATALOG_URLS": "$GW_URL/servers/$TIME_SERVER_UUID",
187-
"MCP_AUTH_TOKEN": "$MCPGATEWAY_BEARER_TOKEN"
186+
"MCP_SERVER_URL": "$GW_URL/servers/$TIME_SERVER_UUID",
187+
"MCP_AUTH": "$MCPGATEWAY_BEARER_TOKEN"
188188
}
189189
}
190190
}

‎docs/docs/tutorials/argocd-helm-deployment-ibm-cloud-iks.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -694,8 +694,8 @@ Add to your Claude Desktop configuration:
694694
"command": "python",
695695
"args": ["-m", "mcpgateway.wrapper"],
696696
"env": {
697-
"MCP_AUTH_TOKEN": "<MCPGATEWAY_BEARER_TOKEN>",
698-
"MCP_SERVER_CATALOG_URLS": "https://mcp-gateway.<CLUSTER_INGRESS_SUBDOMAIN>/servers/UUID_OF_SERVER_1"
697+
"MCP_AUTH": "<MCPGATEWAY_BEARER_TOKEN>",
698+
"MCP_SERVER_URL": "https://mcp-gateway.<CLUSTER_INGRESS_SUBDOMAIN>/servers/UUID_OF_SERVER_1/mcp"
699699
}
700700
}
701701
}

‎docs/docs/using/agents/bee.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ To use MCP tools in the Bee Agent Framework, follow these steps:
3636

3737
```bash
3838
export MCP_GATEWAY_BASE_URL=http://localhost:4444
39-
export MCP_AUTH_TOKEN="your_bearer_token"
39+
export MCP_AUTH="your_bearer_token"
4040
```
4141

4242
---

‎docs/docs/using/clients/claude-desktop.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@ prompt and resource registered in your Gateway.
2626
"command": "python3",
2727
"args": ["-m", "mcpgateway.wrapper"],
2828
"env": {
29-
"MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1",
30-
"MCP_AUTH_TOKEN": "<YOUR_JWT_TOKEN>",
29+
"MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1",
30+
"MCP_AUTH": "<YOUR_JWT_TOKEN>",
3131
"MCP_TOOL_CALL_TIMEOUT": "120"
3232
}
3333
}
@@ -46,8 +46,8 @@ prompt and resource registered in your Gateway.
4646
"command": "docker",
4747
"args": [
4848
"run", "--rm", "--network=host", "-i",
49-
"-e", "MCP_SERVER_CATALOG_URLS=http://localhost:4444/servers/UUID_OF_SERVER_1",
50-
"-e", "MCP_AUTH_TOKEN=<YOUR_JWT_TOKEN>",
49+
"-e", "MCP_SERVER_URL=http://localhost:4444/servers/UUID_OF_SERVER_1",
50+
"-e", "MCP_AUTH=<YOUR_JWT_TOKEN>",
5151
"ghcr.io/ibm/mcp-context-forge:0.5.0",
5252
"python3", "-m", "mcpgateway.wrapper"
5353
]
@@ -67,8 +67,8 @@ If you installed the package globally:
6767
"command": "pipx",
6868
"args": ["run", "python3", "-m", "mcpgateway.wrapper"],
6969
"env": {
70-
"MCP_SERVER_CATALOG_URLS": "http://localhost:4444/servers/UUID_OF_SERVER_1",
71-
"MCP_AUTH_TOKEN": "<YOUR_JWT_TOKEN>"
70+
"MCP_SERVER_URL": "http://localhost:4444/servers/UUID_OF_SERVER_1",
71+
"MCP_AUTH": "<YOUR_JWT_TOKEN>"
7272
}
7373
}
7474
```
@@ -94,8 +94,8 @@ If tools don't appear, open *File ▸ Settings ▸ Developer ▸ View Logs* to s
9494

9595
| Var | Purpose |
9696
| ------------------------- | ------------------------------------------------- |
97-
| `MCP_SERVER_CATALOG_URLS` | One or more `/servers/{id}` endpoints (comma-sep) |
98-
| `MCP_AUTH_TOKEN` | JWT bearer for Gateway auth |
97+
| `MCP_SERVER_URL` | One or more `/servers/{id}` endpoints (comma-sep) |
98+
| `MCP_AUTH` | JWT bearer for Gateway auth |
9999
| `MCP_TOOL_CALL_TIMEOUT` | Per-tool timeout (seconds, optional) |
100100
| `MCP_WRAPPER_LOG_LEVEL` | `DEBUG`, `INFO`, `OFF` (optional) |
101101

‎docs/docs/using/clients/cline.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,8 +51,8 @@ To integrate Cline with your MCP Gateway:
5151
"mcpgateway.wrapper"
5252
],
5353
"env": {
54-
"MCP_SERVER_CATALOG_URLS": "http://localhost:4444",
55-
"MCP_AUTH_TOKEN": "REPLACE_WITH_MCPGATEWAY_BEARER_TOKEN",
54+
"MCP_SERVER_URL": "http://localhost:4444",
55+
"MCP_AUTH": "Bearer REPLACE_WITH_MCPGATEWAY_BEARER_TOKEN",
5656
"MCP_WRAPPER_LOG_LEVEL": "OFF"
5757
}
5858
}

0 commit comments

Comments
 (0)