@jadchene/mcp-gateway-service 0.11.1 → 0.11.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,205 +1,209 @@
1
- English | [简体中文](./README_zh.md)
2
-
3
- # MCP Gateway
4
-
5
- ## Introduction
6
-
7
- MCP Gateway puts multiple MCP services behind one endpoint. An agent connects to the gateway and sees six routing tools; downstream services, tools, and schemas are looked up only when they are needed.
8
-
9
- The project uses the official TypeScript SDK v2 and requires Node.js 24 or later.
10
-
11
- > [!IMPORTANT]
12
- > MCP Gateway v0.6.2 and later accept only MCP `2026-07-28`, `2025-11-25`, and `2025-06-18`. Supported transports are newline-delimited stdio and single-endpoint Streamable HTTP. Standalone HTTP+SSE (`/sse`), `Content-Length` framing, and other protocol revisions are not supported.
13
-
14
- ## Why Use It
15
-
16
- - Keep the agent context small even when many MCP services are configured.
17
- - Connect the agent once, then add or remove downstream services in the gateway config.
18
- - Find tools by name or description and load schemas only when required.
19
- - Use stdio and Streamable HTTP services through the same interface.
20
- - Require user confirmation for selected tool-name patterns, or hide and block matching tools entirely.
21
- - Reload config changes without restarting the gateway.
22
-
23
- ## Quick Start
24
-
25
- ### Install
26
-
27
- ```bash
28
- npm install -g @jadchene/mcp-gateway-service
29
- ```
30
-
31
- Create `config.json`. Replace `your-mcp-service` with the command of an installed MCP server:
32
-
33
- ```json
34
- {
35
- "services": [
36
- {
37
- "serviceId": "tools",
38
- "name": "Tools",
39
- "transport": {
40
- "type": "stdio",
41
- "command": "your-mcp-service"
42
- }
43
- }
44
- ]
45
- }
46
- ```
47
-
48
- ### Stdio
49
-
50
- The agent starts the gateway process, so no separate startup command is needed.
51
-
52
- Codex `config.toml`:
53
-
54
- ```toml
55
- [mcp_servers.gateway]
56
- command = "mcp-gateway-service"
57
- args = ["--config", "./config.json"]
58
- ```
59
-
60
- Claude Code:
61
-
62
- ```bash
63
- claude mcp add gateway -- mcp-gateway-service --config ./config.json
64
- ```
65
-
66
- ### Streamable HTTP
67
-
68
- Start the gateway:
69
-
70
- ```bash
71
- mcp-gateway-service --http --config ./config.json
72
- ```
73
-
74
- The default endpoint is `http://127.0.0.1:3000/mcp`.
75
- HTTP hides `gateway_manage_service` by default. Non-loopback binds require a bearer token in `MCP_GATEWAY_AUTH_TOKEN`.
76
-
77
- Codex `config.toml`:
78
-
79
- ```toml
80
- [mcp_servers.gateway]
81
- url = "http://127.0.0.1:3000/mcp"
82
- ```
83
-
84
- Claude Code:
85
-
86
- ```bash
87
- claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
88
- ```
89
-
90
- ## Configuration and Tools
91
-
92
- ### CLI Options
93
-
94
- | Option | Description | Default |
95
- | --- | --- | --- |
96
- | `--config <path>` | Config file path. | `MCP_GATEWAY_CONFIG`, then `./config.json` |
97
- | `--http` | Enables the Streamable HTTP endpoint. | Disabled |
98
- | `--host <host>` | HTTP bind address. | `127.0.0.1` |
99
- | `--port <port>` | HTTP port. | `3000` |
100
- | `--path <path>` | HTTP endpoint path. | `/mcp` |
101
- | `--auth-token-env <name>` | Environment variable containing the HTTP bearer token. | `MCP_GATEWAY_AUTH_TOKEN` |
102
- | `--http-admin-tools` | Exposes `gateway_manage_service` over authenticated HTTP. | Disabled |
103
- | `--max-concurrent-requests <n>` | Bounds in-flight HTTP requests. | `64` |
104
- | `--max-request-body-bytes <n>` | Rejects HTTP request bodies above this byte limit; maximum configurable value is 64 MiB. | `16777216` (16 MiB) |
105
- | `--max-legacy-sessions <n>` | Bounds retained stateful legacy HTTP sessions. | `256` |
106
- | `--version`, `-v` | Prints the installed version. | — |
107
-
108
- Stdio remains available when `--http` is enabled.
109
-
110
- ### Config File
111
-
112
- ```json
113
- {
114
- "logging": {
115
- "enable": false,
116
- "path": "./logs/mcp-gateway.log"
117
- },
118
- "services": [
119
- {
120
- "serviceId": "local-tools",
121
- "name": "Local Tools",
122
- "confirmationRequiredTools": ["delete_*", "deploy_?"],
123
- "disabledTools": ["internal_*", "legacy_tool"],
124
- "transport": {
125
- "type": "stdio",
126
- "command": "your-mcp-service",
127
- "args": []
128
- }
129
- },
130
- {
131
- "serviceId": "remote-tools",
132
- "name": "Remote Tools",
133
- "transport": {
134
- "type": "http",
135
- "url": "http://127.0.0.1:3200/mcp"
136
- }
137
- }
138
- ]
139
- }
140
- ```
141
-
142
- | Field | Description |
143
- | --- | --- |
144
- | `services` | List of downstream MCP services. |
145
- | `serviceId` | Required unique identifier used by gateway tools. |
146
- | `name` | Required display name. |
147
- | `description` | Optional service description. |
148
- | `enable` | Optional; defaults to `true`. |
149
- | `callTimeoutMs` | Optional downstream tool-call timeout; defaults to 120 seconds. |
150
- | `confirmationRequiredTools` | Optional unique array of case-sensitive full-name glob patterns. `*` matches zero or more characters and `?` matches one character. The gateway asks the upstream user for form elicitation confirmation before calling a matching tool. |
151
- | `disabledTools` | Optional unique array using the same glob syntax. Matching tools are hidden from tool listing and schema lookup, and calls are rejected before reaching the downstream service. |
152
- | `transport.type` | `stdio` or `http`. |
153
- | `transport.command` | Required command for a stdio service. |
154
- | `transport.args` | Optional command arguments for a stdio service. |
155
- | `transport.cwd` | Optional working directory for a stdio service. |
156
- | `transport.env` | Optional environment variables for a stdio service. |
157
- | `transport.inheritEnv` | Opts into inheriting the complete gateway environment; defaults to `false`. |
158
- | `transport.envAllowlist` | Additional process environment names passed to stdio services. |
159
- | `transport.url` | Required Streamable HTTP URL for an HTTP service. |
160
- | `transport.headers` | Optional static headers for an HTTP service. |
161
- | `logging.enable` | Enables file logging; defaults to `false`. |
162
- | `logging.path` | Log file path. Relative paths use the config file directory. |
163
- | `logging.maxBytes` | Active log size before rotation; defaults to 10 MiB. |
164
-
165
- The config file is watched for changes. Invalid updates are rejected and the last valid config stays active. See [config.example.json](./config.example.json) for another example.
166
-
167
- ### Gateway Tools
168
-
169
- | Tool | Description |
170
- | --- | --- |
171
- | `gateway_list_services` | Searches enabled services by identifier or description and can filter by availability. |
172
- | `gateway_get_service` | Shows one service's connection state, protocol revision, server identity, and recent error. |
173
- | `gateway_list_tools` | Searches a service's tools by name or description and can include schemas. |
174
- | `gateway_get_tool_schema` | Returns schemas for exact tool names. |
175
- | `gateway_manage_service` | Reconnects a service or enables/disables it in the config file. |
176
- | `gateway_call_tool` | Calls one downstream tool and returns its MCP result. |
177
-
178
- The usual flow is `gateway_list_services` → `gateway_list_tools` → `gateway_get_tool_schema` when needed → `gateway_call_tool`. Pass `{}` to `gateway_call_tool` when the downstream tool has no arguments.
179
-
180
- Calls matching `confirmationRequiredTools` show the service, tool, and arguments and require approval in the current MCP session. Clients without form elicitation support cannot invoke them. Calls with uncertain outcomes are not retried automatically.
181
-
182
- `disabledTools` takes precedence over `confirmationRequiredTools` when both match. A disabled tool is hidden and rejected immediately without asking for confirmation.
183
-
184
- Agents with Skills support can use the included [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) for the discovery and calling workflow.
185
-
186
- ## Development
187
-
188
- ```bash
189
- git clone https://github.com/jadchene/mcp-gateway.git
190
- cd mcp-gateway
191
- npm install
192
- npm run verify
193
- npm run dev -- --config ./config.json
194
- ```
195
-
196
- Build and run the compiled service:
197
-
198
- ```bash
199
- npm run build
200
- npm start -- --config ./config.json
201
- ```
202
-
203
- ## License
204
-
205
- [MIT](./LICENSE)
1
+ English | [简体中文](./README_zh.md)
2
+
3
+ # MCP Gateway
4
+
5
+ ## Introduction
6
+
7
+ MCP Gateway puts multiple MCP services behind one endpoint. An agent connects to the gateway and sees six routing tools; downstream services, tools, and schemas are looked up only when they are needed.
8
+
9
+ The project uses the official TypeScript SDK v2 and requires Node.js 24 or later.
10
+
11
+ > [!IMPORTANT]
12
+ > MCP Gateway v0.6.2 and later accept only MCP `2026-07-28`, `2025-11-25`, and `2025-06-18`. Supported transports are newline-delimited stdio and single-endpoint Streamable HTTP. Standalone HTTP+SSE (`/sse`), `Content-Length` framing, and other protocol revisions are not supported.
13
+
14
+ ## Why Use It
15
+
16
+ - Keep the agent context small even when many MCP services are configured.
17
+ - Connect the agent once, then add or remove downstream services in the gateway config.
18
+ - Find tools by name or description and load schemas only when required.
19
+ - Use stdio and Streamable HTTP services through the same interface.
20
+ - Require user confirmation for selected tool-name patterns, or hide and block matching tools entirely.
21
+ - Reload config changes without restarting the gateway.
22
+
23
+ ## Quick Start
24
+
25
+ ### Install
26
+
27
+ ```bash
28
+ npm install -g @jadchene/mcp-gateway-service
29
+ ```
30
+
31
+ Create `config.json`. Replace `your-mcp-service` with the command of an installed MCP server:
32
+
33
+ ```json
34
+ {
35
+ "services": [
36
+ {
37
+ "serviceId": "tools",
38
+ "name": "Tools",
39
+ "transport": {
40
+ "type": "stdio",
41
+ "command": "your-mcp-service"
42
+ }
43
+ }
44
+ ]
45
+ }
46
+ ```
47
+
48
+ ### Stdio
49
+
50
+ The agent starts the gateway process, so no separate startup command is needed.
51
+
52
+ Codex `config.toml`:
53
+
54
+ ```toml
55
+ [mcp_servers.gateway]
56
+ command = "mcp-gateway-service"
57
+ args = ["--config", "./config.json"]
58
+ ```
59
+
60
+ Claude Code:
61
+
62
+ ```bash
63
+ claude mcp add gateway -- mcp-gateway-service --config ./config.json
64
+ ```
65
+
66
+ ### Streamable HTTP
67
+
68
+ Start the gateway:
69
+
70
+ ```bash
71
+ mcp-gateway-service --http --config ./config.json
72
+ ```
73
+
74
+ The default endpoint is `http://127.0.0.1:3000/mcp`.
75
+ HTTP hides `gateway_manage_service` by default. Non-loopback binds require a bearer token in `MCP_GATEWAY_AUTH_TOKEN`.
76
+
77
+ Codex `config.toml`:
78
+
79
+ ```toml
80
+ [mcp_servers.gateway]
81
+ url = "http://127.0.0.1:3000/mcp"
82
+ ```
83
+
84
+ Claude Code:
85
+
86
+ ```bash
87
+ claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
88
+ ```
89
+
90
+ ## Configuration and Tools
91
+
92
+ ### CLI Options
93
+
94
+ | Option | Description | Default |
95
+ | --- | --- | --- |
96
+ | `--config <path>` | Config file path. | `MCP_GATEWAY_CONFIG`, then `./config.json` |
97
+ | `--http` | Enables the Streamable HTTP endpoint. | Disabled |
98
+ | `--host <host>` | HTTP bind address. | `127.0.0.1` |
99
+ | `--port <port>` | HTTP port. | `3000` |
100
+ | `--path <path>` | HTTP endpoint path. | `/mcp` |
101
+ | `--auth-token-env <name>` | Environment variable containing the HTTP bearer token. | `MCP_GATEWAY_AUTH_TOKEN` |
102
+ | `--http-admin-tools` | Exposes `gateway_manage_service` over authenticated HTTP. | Disabled |
103
+ | `--max-concurrent-requests <n>` | Bounds in-flight HTTP requests. | `64` |
104
+ | `--max-request-body-bytes <n>` | Rejects HTTP request bodies above this byte limit; maximum configurable value is 64 MiB. | `16777216` (16 MiB) |
105
+ | `--max-legacy-sessions <n>` | Bounds retained stateful legacy HTTP sessions. | `256` |
106
+ | `--version`, `-v` | Prints the installed version. | — |
107
+
108
+ Stdio remains available when `--http` is enabled.
109
+
110
+ ### Config File
111
+
112
+ ```json
113
+ {
114
+ "logging": {
115
+ "enable": false,
116
+ "path": "./logs/mcp-gateway.log"
117
+ },
118
+ "services": [
119
+ {
120
+ "serviceId": "local-tools",
121
+ "name": "Local Tools",
122
+ "confirmationRequiredTools": ["delete_*", "deploy_?"],
123
+ "codexAutoReview": false,
124
+ "disabledTools": ["internal_*", "legacy_tool"],
125
+ "transport": {
126
+ "type": "stdio",
127
+ "command": "your-mcp-service",
128
+ "args": []
129
+ }
130
+ },
131
+ {
132
+ "serviceId": "remote-tools",
133
+ "name": "Remote Tools",
134
+ "transport": {
135
+ "type": "http",
136
+ "url": "http://127.0.0.1:3200/mcp"
137
+ }
138
+ }
139
+ ]
140
+ }
141
+ ```
142
+
143
+ | Field | Description |
144
+ | --- | --- |
145
+ | `services` | List of downstream MCP services. |
146
+ | `serviceId` | Required unique identifier used by gateway tools. |
147
+ | `name` | Required display name. |
148
+ | `description` | Optional service description. |
149
+ | `enable` | Optional; defaults to `true`. |
150
+ | `callTimeoutMs` | Optional downstream tool-call timeout; defaults to 120 seconds. |
151
+ | `confirmationRequiredTools` | Optional unique array of case-sensitive full-name glob patterns. `*` matches zero or more characters and `?` matches one character. The gateway asks the upstream user for form elicitation confirmation before calling a matching tool. |
152
+ | `codexAutoReview` | Optional boolean, defaults to `false`. Set `true` to enable Codex automatic-review metadata for gateway confirmations configured by this service’s `confirmationRequiredTools`. |
153
+ | `disabledTools` | Optional unique array using the same glob syntax. Matching tools are hidden from tool listing and schema lookup, and calls are rejected before reaching the downstream service. |
154
+ | `transport.type` | `stdio` or `http`. |
155
+ | `transport.command` | Required command for a stdio service. |
156
+ | `transport.args` | Optional command arguments for a stdio service. |
157
+ | `transport.cwd` | Optional working directory for a stdio service. |
158
+ | `transport.env` | Optional environment variables for a stdio service. |
159
+ | `transport.inheritEnv` | Opts into inheriting the complete gateway environment; defaults to `false`. |
160
+ | `transport.envAllowlist` | Additional process environment names passed to stdio services. |
161
+ | `transport.url` | Required Streamable HTTP URL for an HTTP service. |
162
+ | `transport.headers` | Optional static headers for an HTTP service. |
163
+ | `logging.enable` | Enables file logging; defaults to `false`. |
164
+ | `logging.path` | Log file path. Relative paths use the config file directory. |
165
+ | `logging.maxBytes` | Active log size before rotation; defaults to 10 MiB. |
166
+
167
+ The config file is watched for changes. Invalid updates are rejected and the last valid config stays active. See [config.example.json](./config.example.json) for another example.
168
+
169
+ ### Gateway Tools
170
+
171
+ | Tool | Description |
172
+ | --- | --- |
173
+ | `gateway_list_services` | Searches enabled services by identifier or description and can filter by availability. |
174
+ | `gateway_get_service` | Shows one service's connection state, protocol revision, server identity, and recent error. |
175
+ | `gateway_list_tools` | Searches a service's tools by name or description and can include schemas. |
176
+ | `gateway_get_tool_schema` | Returns schemas for exact tool names. |
177
+ | `gateway_manage_service` | Reconnects a service or enables/disables it in the config file. |
178
+ | `gateway_call_tool` | Calls one downstream tool and returns its MCP result. |
179
+
180
+ The usual flow is `gateway_list_services` → `gateway_list_tools` → `gateway_get_tool_schema` when needed → `gateway_call_tool`. Pass `{}` to `gateway_call_tool` when the downstream tool has no arguments.
181
+
182
+ Calls matching `confirmationRequiredTools` show the service, tool, and arguments and require approval in the current MCP session. Clients without form elicitation support cannot invoke them. Calls with uncertain outcomes are not retried automatically.
183
+
184
+ Codex automatic-review integration is disabled by default. Set `"codexAutoReview": true` in the selected `services[]` block to enable approval metadata only for gateway confirmations generated by `confirmationRequiredTools`. Downstream confirmation forms and their `_meta` are forwarded unchanged; downstream automatic-review settings operate independently. Codex uses automatic review when `approvals_reviewer = "auto_review"` is enabled; otherwise, use normal Accept / Decline / Cancel confirmation. Approval remains subject to Codex policy.
185
+
186
+ `disabledTools` takes precedence over `confirmationRequiredTools` when both match. A disabled tool is hidden and rejected immediately without asking for confirmation.
187
+
188
+ Agents with Skills support can use the included [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) for the discovery and calling workflow.
189
+
190
+ ## Development
191
+
192
+ ```bash
193
+ git clone https://github.com/jadchene/mcp-gateway.git
194
+ cd mcp-gateway
195
+ npm install
196
+ npm run verify
197
+ npm run dev -- --config ./config.json
198
+ ```
199
+
200
+ Build and run the compiled service:
201
+
202
+ ```bash
203
+ npm run build
204
+ npm start -- --config ./config.json
205
+ ```
206
+
207
+ ## License
208
+
209
+ [MIT](./LICENSE)