8000 docs: revamp and clarify configuration and usage documentation by appleboy · Pull Request #30 · TBXark/mcp-proxy · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

docs: revamp and clarify configuration and usage documentation #30

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 28, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 17 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,16 @@ make build
### Install by go

```bash
# Install the latest version of mcp-proxy
go install github.com/TBXark/mcp-proxy@latest
# Or install stable version
go install github.com/TBXark/mcp-proxy
````

### Docker

> The Docker image supports two MCP calling methods by default: `npx` and `uvx`.

```bash
docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest
# or
Expand All @@ -37,8 +41,8 @@ docker run -d -p 9090:9090 ghcr.io/tbxark/mcp-proxy:latest --config https://exam
## Configuration

The server is configured using a JSON file. Below is an example configuration:
> This is the format for the new version's configuration. The old version's configuration will be automatically converted to the new format's configuration when it is loaded.

> This is the format for the new version's configuration. The old version's configuration will be automatically converted to the new format's configuration when it is loaded.
> You can use [`https://tbxark.github.io/mcp-proxy`](https://tbxark.github.io/mcp-proxy) to convert the configuration of `mcp-proxy` into the configuration that `Claude` can use.

```jsonc
Expand Down Expand Up @@ -97,6 +101,7 @@ The server is configured using a JSON file. Below is an example configuration:
```

### **`options`**

Common options for `mcpProxy` and `mcpServers`.

- `panicIfInvalid`: If true, the server will panic if the client is invalid.
Expand All @@ -107,12 +112,12 @@ Common options for `mcpProxy` and `mcpServers`.
- `list`: A list of tool names to filter (either allow or block based on the `mode`).
> **Tip:** If you don't know the exact tool names, run the proxy once without any `toolFilter` configured. The console will log messages like `<server_name> Adding tool <tool_name>` for each successfully registered tool. You can use these logged names in your `toolFilter` list.

> In the new configuration, the `authTokens` of `mcpProxy` is not a global authentication token, but rather the default authentication token for `mcpProxy`. When `authTokens` is set in `mcpServers`, the value of `authTokens` in `mcpServers` will be used instead of the value in `mcpProxy`. In other words, the `authTokens` of `mcpProxy` serves as a default value and is only applied when `authTokens` is not set in `mcpServers`.

> Other fields are the same.
> In the new configuration, the `authTokens` of `mcpProxy` is not a global authentication token, but rather the default authentication token for `mcpProxy`. When `authTokens` is set in `mcpServers`, the value of `authTokens` in `mcpServers` will be used instead of the value in `mcpProxy`. In other words, the `authTokens` of `mcpProxy` serves as a default value and is only applied when `authTokens` is not set in `mcpServers`. Other fields are the same.

### **`mcpProxy`**

Proxy HTTP server configuration

- `baseURL`: The public accessible URL of the server. This is used to generate the URLs for the clients.
- `addr`: The address the server listens on.
- `name`: The name of the server.
Expand All @@ -123,31 +128,35 @@ Proxy HTTP server configuration
- `options`: Default options for the `mcpServers`.

### **`mcpServers`**

MCP server configuration, Adopt the same configuration format as other MCP Clients.

- `transportType`: The transport type of the MCP client. Except for `streamable-http`, which requires manual configuration, the rest will be automatically configured according to the content of the configuration file.
- `stdio`: The MCP client is a command line tool that is run in a subprocess.
- `sse`: The MCP client is a server that supports SSE (Server-Sent Events).
- `streamable-http`: The MCP client is a server that supports HTTP streaming.

For stdio mcp servers, the `command` field is required.

- `command`: The command to run the MCP client.
- `args`: The arguments to pass to the command.
- `env`: The environment variables to set for the command.
- `options`: Options specific to the client.

For sse mcp servers, the `url` field is required. When the current `url` exists, `sse` will be automatically configured.

- `url`: The URL of the MCP client.
- `headers`: The headers to send with the request to the MCP client.

For http streaming mcp servers, the `url` field is required. and `transportType` need to manually set to `streamable-http`.

- `url`: The URL of the MCP client.
- `headers`: The headers to send with the request to the MCP client.
- `timeout`: The timeout for the request to the MCP client.


## Usage

```
```bash
Usage of mcp-proxy:
-config string
path to config file or a http(s) url (default "config.json")
Expand All @@ -156,6 +165,7 @@ Usage of mcp-proxy:
-version
print version and exit
```

1. The server will start and aggregate the tools and capabilities of the configured MCP clients.
2. When MCP Server type is `sse`, You can access the server at `http(s)://{baseURL}/{clientName}/sse`. (e.g., `https://mcp.example.com/fetch/sse`, based on the example configuration)
3. When MCP Server type is `streamable-http`, You can access the server at `http(s)://{baseURL}/{clientName}/mcp`. (e.g., `https://mcp.example.com/fetch/mcp`, based on the example configuration)
Expand All @@ -168,4 +178,4 @@ Usage of mcp-proxy:

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
0