diff --git a/docs/toolhive/_partials/_client-compat-table.md b/docs/toolhive/_partials/_client-compat-table.md index 78df10b3..92bb2d9a 100644 --- a/docs/toolhive/_partials/_client-compat-table.md +++ b/docs/toolhive/_partials/_client-compat-table.md @@ -1,15 +1,16 @@ -| Client | Supported | Auto-discovery | Notes | -| -------------------------- | --------- | -------------- | ----------------------------------------- | -| GitHub Copilot (VS Code) | ✅ | ✅ | v1.99.0+ or Insiders version | -| Cursor | ✅ | ✅ | v0.47.0+ | -| Roo Code | ✅ | ✅ | v3.9.0+ | -| Cline | ✅ | ✅ | v3.8.5+ | -| Claude Code | ✅ | ✅ | v0.2.54+ | -| PydanticAI | ✅ | ❌ | | -| Continue | ✅ | ❌ | Pre-release extension v1.39+ ([issue][1]) | -| GitHub Copilot (JetBrains) | ❌ | ❌ | No support for HTTP/SSE MCPs ([issue][2]) | -| Claude Desktop | ❌ | ❌ | No support for HTTP/SSE MCPs ([issue][3]) | +| Client | Supported | Auto-configuration | Notes | +| -------------------------- | :-------: | :----------------: | ---------------------------------------------- | +| GitHub Copilot (VS Code) | ✅ | ✅ | v1.100+ or Insiders version | +| Cursor | ✅ | ✅ | v0.50.0+ | +| Roo Code (VS Code) | ✅ | ✅ | v3.19.2+ | +| Cline (VS Code) | ✅ | ✅ | v3.8.5+ (sse only; streamable-http [issue][2]) | +| Claude Code CLI | ✅ | ✅ | v1.0.27+ | +| GitHub Copilot (JetBrains) | ✅ | ❌ | v1.5.47+ | +| Continue (VS Code) | ✅ | ❌ | v1.0.14+ | +| Continue (JetBrains) | ✅ | ❌ | v1.0.23+ | +| PydanticAI | ✅ | ❌ | v0.2.18+ | +| ChatGPT Desktop | ❌ | ❌ | No support for HTTP/SSE MCPs | +| Claude Desktop | ❌ | ❌ | No support for HTTP/SSE MCPs ([issue][1]) | -[1]: https://github.com/continuedev/continue/issues/5359 -[2]: https://github.com/microsoft/copilot-intellij-feedback/issues/224 -[3]: https://github.com/orgs/modelcontextprotocol/discussions/16 +[1]: https://github.com/orgs/modelcontextprotocol/discussions/16 +[2]: https://github.com/cline/cline/issues/4391 diff --git a/docs/toolhive/guides-cli/client-configuration.md b/docs/toolhive/guides-cli/client-configuration.md index 966b0723..96780c5c 100644 --- a/docs/toolhive/guides-cli/client-configuration.md +++ b/docs/toolhive/guides-cli/client-configuration.md @@ -17,7 +17,8 @@ You can configure clients with ToolHive in three ways: clients. 2. **Manual registration**: Register specific clients for ToolHive to manage. 3. **Custom configuration**: For unsupported clients or custom setups, configure - them to connect to ToolHive-managed MCP servers using the SSE protocol. + them to connect to ToolHive-managed MCP servers using the SSE or Streamable + HTTP protocol. With the first two methods, ToolHive automatically updates client configuration when you start or remove an MCP server. For a complete list of supported clients @@ -113,8 +114,8 @@ thv config remove-client If you have other clients or development libraries that ToolHive doesn't directly support, you can still configure them to use ToolHive-managed MCP -servers as long as they support the SSE protocol. Check your client or library -documentation for configuration details. +servers as long as they support the SSE or Streamable HTTP protocol. Check your +client or library documentation for configuration details. List your running MCP servers to get the URL: diff --git a/docs/toolhive/guides-cli/run-mcp-servers.mdx b/docs/toolhive/guides-cli/run-mcp-servers.mdx index 651f770b..1e364780 100644 --- a/docs/toolhive/guides-cli/run-mcp-servers.mdx +++ b/docs/toolhive/guides-cli/run-mcp-servers.mdx @@ -164,14 +164,22 @@ ToolHive supports the following transport methods: doesn't have direct access to the network or the host machine. - **HTTP with SSE (server-sent events)** (`sse`):\ - ToolHive creates a reverse proxy that forwards requests to the container. This - means the container itself doesn't directly expose any ports. + ToolHive creates a reverse proxy that forwards requests to the container using + the HTTP/SSE protocol. -- **Streamable HTTP** - coming soon!\ - The March 2025 revision of the MCP specification replaced the HTTP+SSE - transport with Streamable HTTP. Follow the - [GitHub issue](https://github.com/stacklok/toolhive/issues/54) to be notified - when this feature is available in ToolHive. +- **Streamable HTTP** (`streamable-http`):\ + ToolHive creates a reverse proxy that forwards requests to the container using + the Streamable HTTP protocol, which replaced SSE in the MCP specification as + of the `2025-03-26` revision. + +:::info + +We are actively monitoring the adoption of the Streamable HTTP protocol across +the client ecosystem. Once we confirm that ToolHive's supported clients support +Streamable HTTP, we will make it the default proxy transport method for stdio +servers. + +::: ### Run a server from a Docker image @@ -181,15 +189,15 @@ name for the server instance, the transport method, and any additional arguments required by the MCP server. ```bash -thv run [--name ] [--transport ] -- +thv run [--name ] [--transport ] -- ``` For example, to run an MCP server from a Docker image named -`my-mcp-server-image` that uses the SSE transport method and takes additional -arguments: +`my-mcp-server-image` that uses the Streamable HTTP transport method and takes +additional arguments: ```bash -thv run --name my-mcp-server --transport sse my-mcp-server-image:latest -- --arg1 value1 --arg2 value2 +thv run --name my-mcp-server --transport streamable-http my-mcp-server-image:latest -- --arg1 value1 --arg2 value2 ``` Check your MCP server's documentation for the required arguments. @@ -207,8 +215,8 @@ When you run an MCP server from a Docker image, ToolHive: toolhive: true toolhive-name: my-mcp-server ``` -4. Sets up the specified transport method (`--transport stdio` or - `--transport sse`). +4. Sets up the specified `--transport` method (`stdio`, `sse`, or + `streamable-http`). ::: diff --git a/docs/toolhive/index.mdx b/docs/toolhive/index.mdx index 3236390a..98ea6228 100644 --- a/docs/toolhive/index.mdx +++ b/docs/toolhive/index.mdx @@ -57,11 +57,11 @@ with sensible security controls and container-native simplicity. ## Architecture overview -ToolHive exposes an HTTP/SSE proxy to forward requests to MCP servers running in +ToolHive exposes an HTTP proxy to forward requests to MCP servers running in containers. The proxy communicates with MCP servers via standard input/output -(stdio) or server-sent events (SSE). The ToolHive CLI interacts with Docker or -Podman via the Docker socket API, letting it manage containers and their -configurations. +(stdio), server-sent events (SSE), or Streamable HTTP. The ToolHive CLI +interacts with Docker or Podman via the Docker socket API, letting it manage +containers and their configurations. ```mermaid flowchart LR @@ -69,11 +69,14 @@ flowchart LR direction LR mcp1["MCP server
container"] mcp2["MCP server
container"] + mcp3["MCP server
container"] end proxy1["SSE proxy"] -- stdio --> mcp1 proxy2["SSE proxy"] -- SSE --> mcp2 + proxy3["HTTP proxy"] -- Streamable
HTTP --> mcp3 T["ToolHive CLI"] -- Socket API --> container C["Client"] -- HTTP/SSE --> proxy1 & proxy2 + C -- HTTP --> proxy3 T ~~~ C ``` diff --git a/docs/toolhive/reference/client-compatibility.mdx b/docs/toolhive/reference/client-compatibility.mdx index 1edcf9ce..b0100886 100644 --- a/docs/toolhive/reference/client-compatibility.mdx +++ b/docs/toolhive/reference/client-compatibility.mdx @@ -16,8 +16,11 @@ We've tested ToolHive with these clients: +The minimum versions listed are the earliest versions that support the +Streamable HTTP transport protocol. + You can also use other clients and development libraries that support the SSE -protocol, but you'll need to configure them manually. +and/or Streamable HTTP protocol, but you'll need to configure them manually. ## Client requirements @@ -67,7 +70,8 @@ Example configuration: "mcp": { "servers": { "github": { "url": "http://localhost:19046/sse#github", "type": "sse" }, - "fetch": { "url": "http://localhost:43832/sse#fetch", "type": "sse" } + "fetch": { "url": "http://localhost:43832/sse#fetch", "type": "sse" }, + "osv": { "url": "http://localhost:51712/mcp", "type": "http" } } } } @@ -105,11 +109,14 @@ Example configuration: { "mcpServers": { "github": { "url": "http://localhost:19046/sse#github" }, - "fetch": { "url": "http://localhost:43832/sse#fetch" } + "fetch": { "url": "http://localhost:43832/sse#fetch" }, + "osv": { "url": "http://localhost:51712/mcp" } } } ``` +Cursor automatically detects the transport mode for HTTP MCP servers. + When you register Cursor as a client or enable auto-discovery, ToolHive automatically updates the global MCP configuration file whenever you run an MCP server. You can also @@ -131,7 +138,8 @@ Example configuration: "mcpServers": { "github": { "url": "http://localhost:19046/sse#github", "type": "sse" }, - "fetch": { "url": "http://localhost:43832/sse#fetch", "type": "sse" } + "fetch": { "url": "http://localhost:43832/sse#fetch", "type": "sse" }, + "osv": { "url": "http://localhost:51712/mcp", "type": "http" } } } ``` @@ -172,8 +180,9 @@ Example configuration: ```json { "mcpServers": { - "github": { "url": "http://localhost:19046/sse#github" }, - "fetch": { "url": "http://localhost:43832/sse#fetch" } + "github": { "url": "http://localhost:19046/sse#github", "type": "sse" }, + "fetch": { "url": "http://localhost:43832/sse#fetch", "type": "sse" }, + "osv": { "url": "http://localhost:51712/mcp", "type": "streamable-http" } } } ``` @@ -194,15 +203,20 @@ the MCP server URL manually. For [PydanticAI](https://ai.pydantic.dev/), set the MCP server URL in your code: ```python -from pydantic_ai.mcp import MCPServerHTTP +from pydantic_ai.mcp import MCPServerSSE +from pydantic_ai.mcp import MCPServerStreamableHTTP -server = MCPServerHTTP(url='http://localhost:43832/sse#fetch') +# For Server-Sent Events (SSE) +server = MCPServerSSE(url='http://localhost:43832/sse#fetch') + +# For Streamable HTTP +server = MCPServerStreamableHTTP(url='http://localhost:51712/mcp') ``` ### Example: Continue -For the [Continue](https://continue.dev) extension in VS Code, edit your -`~/.continue/config.yaml` file or project-specific +For the [Continue](https://continue.dev) extension in VS Code or JetBrains, edit +your `~/.continue/config.yaml` file or project-specific `.continue/mcpServers/.yaml` file to include the MCP server URL: ```yaml @@ -212,6 +226,28 @@ mcpServers: url: http://localhost:43832/sse#fetch ``` +Continue supports SSE (`type: sse`) and Streamable HTTP +(`type: streamable-http`) transports. + +### Example: Copilot for JetBrains IDEs + +For the +[GitHub Copilot plugin in JetBrains IDEs](https://plugins.jetbrains.com/plugin/17718-github-copilot) +(IntelliJ, Pydantic, etc.), edit your `~/.config/github-copilot/mcp.json` file +to include the MCP server URL: + +```json +{ + "servers": { + "fetch": { "url": "http://localhost:43832/sse#fetch", "type": "sse" }, + "osv": { "url": "http://localhost:51712/mcp", "type": "http" } + } +} +``` + +Copilot for JetBrains supports SSE (`"type": "sse"`) and Streamable HTTP +(`"type": "streamable-http"`) transports. + ## Related information - [Client configuration](../guides-cli/client-configuration.md)