@jadchene/mcp-gateway-service 0.6.5 → 0.7.0

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,188 +1,196 @@
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
- - Reload config changes without restarting the gateway.
21
-
22
- ## Quick Start
23
-
24
- ### Install
25
-
26
- ```bash
27
- npm install -g @jadchene/mcp-gateway-service
28
- ```
29
-
30
- Create `config.json`. Replace `your-mcp-service` with the command of an installed MCP server:
31
-
32
- ```json
33
- {
34
- "services": [
35
- {
36
- "serviceId": "tools",
37
- "name": "Tools",
38
- "transport": {
39
- "type": "stdio",
40
- "command": "your-mcp-service"
41
- }
42
- }
43
- ]
44
- }
45
- ```
46
-
47
- ### Stdio
48
-
49
- The agent starts the gateway process, so no separate startup command is needed.
50
-
51
- Codex `config.toml`:
52
-
53
- ```toml
54
- [mcp_servers.gateway]
55
- command = "mcp-gateway-service"
56
- args = ["--config", "./config.json"]
57
- ```
58
-
59
- Claude Code:
60
-
61
- ```bash
62
- claude mcp add gateway -- mcp-gateway-service --config ./config.json
63
- ```
64
-
65
- ### Streamable HTTP
66
-
67
- Start the gateway:
68
-
69
- ```bash
70
- mcp-gateway-service --http --config ./config.json
71
- ```
72
-
73
- The default endpoint is `http://127.0.0.1:3000/mcp`.
74
-
75
- Codex `config.toml`:
76
-
77
- ```toml
78
- [mcp_servers.gateway]
79
- url = "http://127.0.0.1:3000/mcp"
80
- ```
81
-
82
- Claude Code:
83
-
84
- ```bash
85
- claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
86
- ```
87
-
88
- ## Configuration and Tools
89
-
90
- ### CLI Options
91
-
92
- | Option | Description | Default |
93
- | --- | --- | --- |
94
- | `--config <path>` | Config file path. | `MCP_GATEWAY_CONFIG`, then `./config.json` |
95
- | `--http` | Enables the Streamable HTTP endpoint. | Disabled |
96
- | `--host <host>` | HTTP bind address. | `127.0.0.1` |
97
- | `--port <port>` | HTTP port. | `3000` |
98
- | `--path <path>` | HTTP endpoint path. | `/mcp` |
99
- | `--version`, `-v` | Prints the installed version. | — |
100
-
101
- Stdio remains available when `--http` is enabled.
102
-
103
- ### Config File
104
-
105
- ```json
106
- {
107
- "logging": {
108
- "enable": false,
109
- "path": "./logs/mcp-gateway.log"
110
- },
111
- "services": [
112
- {
113
- "serviceId": "local-tools",
114
- "name": "Local Tools",
115
- "transport": {
116
- "type": "stdio",
117
- "command": "your-mcp-service",
118
- "args": []
119
- }
120
- },
121
- {
122
- "serviceId": "remote-tools",
123
- "name": "Remote Tools",
124
- "transport": {
125
- "type": "http",
126
- "url": "http://127.0.0.1:3200/mcp"
127
- }
128
- }
129
- ]
130
- }
131
- ```
132
-
133
- | Field | Description |
134
- | --- | --- |
135
- | `services` | List of downstream MCP services. |
136
- | `serviceId` | Required unique identifier used by gateway tools. |
137
- | `name` | Required display name. |
138
- | `description` | Optional service description. |
139
- | `enable` | Optional; defaults to `true`. |
140
- | `transport.type` | `stdio` or `http`. |
141
- | `transport.command` | Required command for a stdio service. |
142
- | `transport.args` | Optional command arguments for a stdio service. |
143
- | `transport.cwd` | Optional working directory for a stdio service. |
144
- | `transport.env` | Optional environment variables for a stdio service. |
145
- | `transport.url` | Required Streamable HTTP URL for an HTTP service. |
146
- | `transport.headers` | Optional static headers for an HTTP service. |
147
- | `logging.enable` | Enables file logging; defaults to `false`. |
148
- | `logging.path` | Log file path. Relative paths use the config file directory. |
149
-
150
- 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.
151
-
152
- ### Gateway Tools
153
-
154
- | Tool | Description |
155
- | --- | --- |
156
- | `gateway_list_services` | Lists configured services and their availability. |
157
- | `gateway_get_service` | Shows one service's connection state, protocol revision, server identity, and recent error. |
158
- | `gateway_list_tools` | Searches a service's tools by name or description and can include schemas. |
159
- | `gateway_get_tool_schema` | Returns schemas for exact tool names. |
160
- | `gateway_manage_service` | Reconnects a service or enables/disables it in the config file. |
161
- | `gateway_call_tool` | Calls one downstream tool and returns its MCP result. |
162
-
163
- 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.
164
-
165
- Calls keep the downstream tool's original side effects and confirmation rules. Enabling or disabling a service with `gateway_manage_service` updates the config file.
166
-
167
- Agents with Skills support can use the included [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) for the discovery and calling workflow.
168
-
169
- ## Development
170
-
171
- ```bash
172
- git clone https://github.com/jadchene/mcp-gateway.git
173
- cd mcp-gateway
174
- npm install
175
- npm run verify
176
- npm run dev -- --config ./config.json
177
- ```
178
-
179
- Build and run the compiled service:
180
-
181
- ```bash
182
- npm run build
183
- npm start -- --config ./config.json
184
- ```
185
-
186
- ## License
187
-
188
- [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
+ - Reload config changes without restarting the gateway.
21
+
22
+ ## Quick Start
23
+
24
+ ### Install
25
+
26
+ ```bash
27
+ npm install -g @jadchene/mcp-gateway-service
28
+ ```
29
+
30
+ Create `config.json`. Replace `your-mcp-service` with the command of an installed MCP server:
31
+
32
+ ```json
33
+ {
34
+ "services": [
35
+ {
36
+ "serviceId": "tools",
37
+ "name": "Tools",
38
+ "transport": {
39
+ "type": "stdio",
40
+ "command": "your-mcp-service"
41
+ }
42
+ }
43
+ ]
44
+ }
45
+ ```
46
+
47
+ ### Stdio
48
+
49
+ The agent starts the gateway process, so no separate startup command is needed.
50
+
51
+ Codex `config.toml`:
52
+
53
+ ```toml
54
+ [mcp_servers.gateway]
55
+ command = "mcp-gateway-service"
56
+ args = ["--config", "./config.json"]
57
+ ```
58
+
59
+ Claude Code:
60
+
61
+ ```bash
62
+ claude mcp add gateway -- mcp-gateway-service --config ./config.json
63
+ ```
64
+
65
+ ### Streamable HTTP
66
+
67
+ Start the gateway:
68
+
69
+ ```bash
70
+ mcp-gateway-service --http --config ./config.json
71
+ ```
72
+
73
+ The default endpoint is `http://127.0.0.1:3000/mcp`.
74
+ HTTP hides `gateway_manage_service` by default. Non-loopback binds require a bearer token in `MCP_GATEWAY_AUTH_TOKEN`.
75
+
76
+ Codex `config.toml`:
77
+
78
+ ```toml
79
+ [mcp_servers.gateway]
80
+ url = "http://127.0.0.1:3000/mcp"
81
+ ```
82
+
83
+ Claude Code:
84
+
85
+ ```bash
86
+ claude mcp add --transport http gateway http://127.0.0.1:3000/mcp
87
+ ```
88
+
89
+ ## Configuration and Tools
90
+
91
+ ### CLI Options
92
+
93
+ | Option | Description | Default |
94
+ | --- | --- | --- |
95
+ | `--config <path>` | Config file path. | `MCP_GATEWAY_CONFIG`, then `./config.json` |
96
+ | `--http` | Enables the Streamable HTTP endpoint. | Disabled |
97
+ | `--host <host>` | HTTP bind address. | `127.0.0.1` |
98
+ | `--port <port>` | HTTP port. | `3000` |
99
+ | `--path <path>` | HTTP endpoint path. | `/mcp` |
100
+ | `--auth-token-env <name>` | Environment variable containing the HTTP bearer token. | `MCP_GATEWAY_AUTH_TOKEN` |
101
+ | `--http-admin-tools` | Exposes `gateway_manage_service` over authenticated HTTP. | Disabled |
102
+ | `--max-concurrent-requests <n>` | Bounds in-flight HTTP requests. | `64` |
103
+ | `--version`, `-v` | Prints the installed version. | — |
104
+
105
+ Stdio remains available when `--http` is enabled.
106
+
107
+ ### Config File
108
+
109
+ ```json
110
+ {
111
+ "logging": {
112
+ "enable": false,
113
+ "path": "./logs/mcp-gateway.log"
114
+ },
115
+ "services": [
116
+ {
117
+ "serviceId": "local-tools",
118
+ "name": "Local Tools",
119
+ "transport": {
120
+ "type": "stdio",
121
+ "command": "your-mcp-service",
122
+ "args": []
123
+ }
124
+ },
125
+ {
126
+ "serviceId": "remote-tools",
127
+ "name": "Remote Tools",
128
+ "transport": {
129
+ "type": "http",
130
+ "url": "http://127.0.0.1:3200/mcp"
131
+ }
132
+ }
133
+ ]
134
+ }
135
+ ```
136
+
137
+ | Field | Description |
138
+ | --- | --- |
139
+ | `services` | List of downstream MCP services. |
140
+ | `serviceId` | Required unique identifier used by gateway tools. |
141
+ | `name` | Required display name. |
142
+ | `description` | Optional service description. |
143
+ | `enable` | Optional; defaults to `true`. |
144
+ | `callTimeoutMs` | Optional downstream tool-call timeout; defaults to 120 seconds. |
145
+ | `transport.type` | `stdio` or `http`. |
146
+ | `transport.command` | Required command for a stdio service. |
147
+ | `transport.args` | Optional command arguments for a stdio service. |
148
+ | `transport.cwd` | Optional working directory for a stdio service. |
149
+ | `transport.env` | Optional environment variables for a stdio service. |
150
+ | `transport.inheritEnv` | Opts into inheriting the complete gateway environment; defaults to `false`. |
151
+ | `transport.envAllowlist` | Additional process environment names passed to stdio services. |
152
+ | `transport.url` | Required Streamable HTTP URL for an HTTP service. |
153
+ | `transport.headers` | Optional static headers for an HTTP service. |
154
+ | `logging.enable` | Enables file logging; defaults to `false`. |
155
+ | `logging.path` | Log file path. Relative paths use the config file directory. |
156
+ | `logging.maxBytes` | Active log size before rotation; defaults to 10 MiB. |
157
+
158
+ 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.
159
+
160
+ ### Gateway Tools
161
+
162
+ | Tool | Description |
163
+ | --- | --- |
164
+ | `gateway_list_services` | Lists configured services and their availability. |
165
+ | `gateway_get_service` | Shows one service's connection state, protocol revision, server identity, and recent error. |
166
+ | `gateway_list_tools` | Searches a service's tools by name or description and can include schemas. |
167
+ | `gateway_get_tool_schema` | Returns schemas for exact tool names. |
168
+ | `gateway_manage_service` | Reconnects a service or enables/disables it in the config file. |
169
+ | `gateway_call_tool` | Calls one downstream tool and returns its MCP result. |
170
+
171
+ 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.
172
+
173
+ Calls keep the downstream tool's original side effects and confirmation rules. An uncertain `gateway_call_tool` failure is never replayed automatically. Enabling or disabling a service with `gateway_manage_service` atomically updates the config file.
174
+
175
+ Agents with Skills support can use the included [MCP Gateway Skill](./skills/mcp-gateway/SKILL.md) for the discovery and calling workflow.
176
+
177
+ ## Development
178
+
179
+ ```bash
180
+ git clone https://github.com/jadchene/mcp-gateway.git
181
+ cd mcp-gateway
182
+ npm install
183
+ npm run verify
184
+ npm run dev -- --config ./config.json
185
+ ```
186
+
187
+ Build and run the compiled service:
188
+
189
+ ```bash
190
+ npm run build
191
+ npm start -- --config ./config.json
192
+ ```
193
+
194
+ ## License
195
+
196
+ [MIT](./LICENSE)