Skip to content

docs: add Docker MCP Gateway streaming transport documentation #6558

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.

Sign up for GitHub

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

Closed
wants to merge 1 commit into from
Closed

docs: add Docker MCP Gateway streaming transport documentation #6558

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,8 @@ Roo Code comes with powerful [tools](https://docs.roocode.com/basic-usage/how-to

MCP extends Roo Code's capabilities by allowing you to add unlimited custom tools. Integrate with external APIs, connect to databases, or create specialized development tools - MCP provides the framework to expand Roo Code's functionality to meet your specific needs.

> **Note:** When using Docker MCP Gateway with streaming transport, see our [Docker MCP Gateway configuration guide](docs/docker-mcp-gateway-streaming.md) for important URL requirements.

### Customization

Make Roo Code work your way with:
Expand Down
60 changes: 60 additions & 0 deletions docs/docker-mcp-gateway-streaming.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Docker MCP Gateway - Streaming Transport Configuration

## Overview

When using the Docker MCP Gateway with the `streaming` transport mode, it's important to understand the correct URL configuration to avoid connection errors.

## Issue

When connecting an MCP client to the Docker MCP Gateway using the `streaming` transport (`docker mcp gateway run --transport streaming`), the connection will fail with errors like "Invalid session ID" if the client is configured to connect to the root URL (e.g., `http://localhost:8080`).
Copy link
Contributor Author

@roomote roomote bot Aug 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The document mentions but doesn't show a complete example. Would it be helpful to add a full command example with all necessary parameters for starting the gateway?


## Root Cause

The Docker MCP Gateway, when running in `streaming` mode, does not serve its MCP functionality from the root path of the server. Instead, it expects all MCP requests to be sent to the `/mcp` endpoint.

## Solution

### Correct Configuration

When configuring your MCP client to connect to a Docker MCP Gateway running with streaming transport, you must include the `/mcp` path in the URL:

```json
{
Copy link
Contributor Author

@roomote roomote bot Aug 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The JSON examples use tabs for indentation, which is inconsistent with typical JSON formatting standards. Consider using 2 or 4 spaces instead:

"mcpServers": {
"Docker_MCP_Gateway_streaming": {
"type": "streamable-http",
"url": "http://localhost:8080/mcp"
}
}
}
```

### Incorrect Configuration (Will Fail)

```json
{
"mcpServers": {
"Docker_MCP_Gateway_streaming": {
"type": "streamable-http",
"url": "http://localhost:8080" // Missing /mcp path
}
}
}
```

## Quick Reference

| Transport Type | Correct URL Format |
Copy link
Contributor Author

@roomote roomote bot Aug 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The quick reference table only shows the streaming transport. Consider either:

  1. Adding other transport types with their URL formats, or
  2. Explicitly stating that this requirement is unique to streaming transport

This would make the documentation more comprehensive.

| -------------- | --------------------------- |
| Streaming | `http://localhost:8080/mcp` |

## Additional Notes

- This requirement is specific to the `streaming` transport mode
Copy link
Contributor Author

@roomote roomote bot Aug 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this path requirement specific only to the streaming transport? It would be helpful to clarify whether other transport modes have different requirements or if this applies universally.

- The port number (8080) may vary based on your Docker configuration
- Always ensure the `/mcp` path is included when using streaming transport

## Related Links

- [MCP Documentation](https://docs.roocode.com/advanced-usage/mcp)
- [Docker MCP Toolkit Documentation](https://docs.roocode.com/advanced-usage/mcp#docker-mcp-toolkit)
Copy link
Contributor Author

@roomote roomote bot Aug 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a troubleshooting section with common error messages users might encounter (like "Invalid session ID") and their solutions. This would help users debug issues more effectively.