Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

refactor(mcp): move MCP client out of utility into internal/mcp/client (#21150)

xugangqiang838cbf451d5a
diff --git a/internal/agent/component/agent_mcp.go b/internal/agent/component/agent_mcp.go
index 633d781178..d05aad18ca 100644
--- a/internal/agent/component/agent_mcp.go
+++ b/internal/agent/component/agent_mcp.go
@@ -14,8 +14,9 @@ import (
"ragflow/internal/agent/runtime"
agenttool "ragflow/internal/agent/tool"
"ragflow/internal/dao"
+ mcpclient "ragflow/internal/mcp/client"
"ragflow/internal/permission"
- "ragflow/internal/utility"
+ servercfg "ragflow/internal/server"
)
// buildAgentMCPTools binds the saved tool selection to servers the canvas can use.
@@ -25,8 +26,8 @@ func buildAgentMCPTools(ctx context.Context, db *gorm.DB, raw any, timeout time.
return nil, nil
}
var selections []struct {
- ID string `json:"mcp_id"`
- Tools map[string]utility.Tool `json:"tools"`
+ ID string `json:"mcp_id"`
+ Tools map[string]mcpclient.Tool `json:"tools"`
}
data, err := json.Marshal(raw)
if err != nil {
@@ -82,11 +83,13 @@ func buildAgentMCPTools(ctx context.Context, db *gorm.DB, raw any, timeout time.
for key, value := range server.Variables {
variables[key] = fmt.Sprint(value)
}
+ allowPrivateHosts := servercfg.MCPAllowPrivateHosts()
for _, name := range slices.Sorted(maps.Keys(selection.Tools)) {
descriptor := selection.Tools[name]
descriptor.Name = name
- adapter := agenttool.NewMCPToolAdapterWithOptions(descriptor, utility.CallOptions{
+ adapter := agenttool.NewMCPToolAdapterWithOptions(descriptor, mcpclient.CallOptions{
URL: server.URL, ServerType: server.ServerType, Headers: headers, Variables: variables, Timeout: timeout,
+ AllowPrivateHosts: allowPrivateHosts,
})
adapter.SetVisibleName(fmt.Sprintf("%s_%d", name, toolIndex))
toolIndex++
diff --git a/internal/agent/component/agent_mcp_test.go b/internal/agent/component/agent_mcp_test.go
index b0cea77fc3..2b03d3408b 100644
--- a/internal/agent/component/agent_mcp_test.go
+++ b/internal/agent/component/agent_mcp_test.go
@@ -10,6 +10,7 @@ import (
"ragflow/internal/common"
"ragflow/internal/entity"
"ragflow/internal/entity/models"
+ mcpclient "ragflow/internal/mcp/client"
"ragflow/internal/utility"
"strings"
"sync/atomic"
@@ -80,7 +81,7 @@ func TestAgentMCPModelDispatch(t *testing.T) {
pinned := utility.PinnedHTTPClient
utility.PinnedHTTPClient = func(string, string, time.Duration) *http.Client { return mcp.Client() }
t.Cleanup(func() { utility.PinnedHTTPClient = pinned })
- if err := db.Create(&entity.MCPServer{ID: "mcp", TenantID: "tenant", Name: "route server", URL: mcp.URL, ServerType: utility.TransportStreamableHTTP, Headers: entity.JSONMap{"Authorization": "Bearer ${authorization_token}"}, Variables: entity.JSONMap{"authorization_token": authToken}}).Error; err != nil {
+ if err := db.Create(&entity.MCPServer{ID: "mcp", TenantID: "tenant", Name: "route server", URL: mcp.URL, ServerType: mcpclient.TransportStreamableHTTP, Headers: entity.JSONMap{"Authorization": "Bearer ${authorization_token}"}, Variables: entity.JSONMap{"authorization_token": authToken}}).Error; err != nil {
t.Fatal(err)
}
addAgentMCPPermissionFixtures(t, db)
@@ -177,7 +178,7 @@ func TestAgentMCPToolNamesDoNotCollide(t *testing.T) {
}
pushComponentDB(t, db)
for _, id := range []string{"first", "second"} {
- if err := db.Create(&entity.MCPServer{ID: id, TenantID: "tenant", Name: id, URL: "https://example.com/mcp", ServerType: utility.TransportStreamableHTTP}).Error; err != nil {
+ if err := db.Create(&entity.MCPServer{ID: id, TenantID: "tenant", Name: id, URL: "https://example.com/mcp", ServerType: mcpclient.TransportStreamableHTTP}).Error; err != nil {
t.Fatal(err)
}
}
diff --git a/internal/agent/tool/mcp.go b/internal/agent/tool/mcp.go
index ebb62052a3..bf4370c040 100644
--- a/internal/agent/tool/mcp.go
+++ b/internal/agent/tool/mcp.go
@@ -16,9 +16,10 @@
// Package tool — MCP (Model Context Protocol) wrapper.
//
-// Wraps a single MCP-server-discovered tool (utility/mcpclient.Tool) as
+// Wraps a single MCP-server-discovered tool (mcpclient.Tool) as
// an eino BaseTool so it can be invoked from inside the Agent's
-// ReAct loop. Discovery and invocation use the utility MCP client.
+// ReAct loop. Discovery and invocation use the MCP client
+// (ragflow/internal/mcp/client).
package tool
import (
@@ -28,7 +29,7 @@ import (
"net/http"
"time"
- mcpclient "ragflow/internal/utility"
+ mcpclient "ragflow/internal/mcp/client"
"github.com/cloudwego/eino/components/tool"
"github.com/cloudwego/eino/schema"
@@ -48,14 +49,15 @@ import (
// a URL (legacy callers) fall back to the "not yet wired"
// sentinel so existing call sites don't break.
type MCPToolAdapter struct {
- mcpTool mcpclient.Tool
- visibleName string
- serverType string
- variables map[string]string
- serverURL string
- headers map[string]string
- timeout time.Duration
- httpClient *http.Client
+ mcpTool mcpclient.Tool
+ visibleName string
+ serverType string
+ variables map[string]string
+ serverURL string
+ headers map[string]string
+ timeout time.Duration
+ httpClient *http.Client
+ allowPrivateHosts bool
}
// NewMCPToolAdapter constructs a wrapper for a single MCP tool.
@@ -94,7 +96,7 @@ func NewMCPToolAdapterFull(t mcpclient.Tool, serverURL string, headers map[strin
// NewMCPToolAdapterWithOptions preserves the server transport and header variables.
func NewMCPToolAdapterWithOptions(t mcpclient.Tool, opts mcpclient.CallOptions) *MCPToolAdapter {
- return &MCPToolAdapter{mcpTool: t, serverURL: opts.URL, serverType: opts.ServerType, headers: opts.Headers, variables: opts.Variables, timeout: opts.Timeout, httpClient: opts.HTTPClient}
+ return &MCPToolAdapter{mcpTool: t, serverURL: opts.URL, serverType: opts.ServerType, headers: opts.Headers, variables: opts.Variables, timeout: opts.Timeout, httpClient: opts.HTTPClient, allowPrivateHosts: opts.AllowPrivateHosts}
}
// Name returns the underlying MCP tool name.
@@ -148,14 +150,15 @@ func (m *MCPToolAdapter) InvokableRun(ctx context.Context, argumentsInJSON strin
return "", mErr
}
res, err := mcpclient.CallTool(ctx, mcpclient.CallOptions{
- URL: m.serverURL,
- ServerType: m.serverType,
- Variables: m.variables,
- Headers: m.headers,
- ToolName: m.mcpTool.Name,
- Arguments: argsJSON,
- Timeout: m.timeout,
- HTTPClient: m.httpClient,
+ URL: m.serverURL,
+ ServerType: m.serverType,
+ Variables: m.variables,
+ Headers: m.headers,
+ ToolName: m.mcpTool.Name,
+ Arguments: argsJSON,
+ Timeout: m.timeout,
+ HTTPClient: m.httpClient,
+ AllowPrivateHosts: m.allowPrivateHosts,
})
if err != nil {
return "", err
diff --git a/internal/agent/tool/mcp_test.go b/internal/agent/tool/mcp_test.go
index 4c7e04b7e0..c1da943f0b 100644
--- a/internal/agent/tool/mcp_test.go
+++ b/internal/agent/tool/mcp_test.go
@@ -27,7 +27,7 @@ import (
"testing"
"time"
- mcpclient "ragflow/internal/utility"
+ mcpclient "ragflow/internal/mcp/client"
)
// TestMCPToolAdapter_InfoReturnsMCPDescriptor: the eino ToolInfo
@@ -430,7 +430,7 @@ func TestMCPToolAdapter_InvokableRunIsError(t *testing.T) {
// mcpLoopbackOverride swaps the SSRF guard's resolver for the
// duration of the test so httptest's 127.0.0.1 server is
// accepted. The pattern mirrors the one used by
-// utility/mcp_client_test.go's allowLoopbackForTests helper.
+// internal/mcp/client/mcp_client_test.go's allowLoopbackForTests helper.
func mcpLoopbackOverride(t *testing.T) func() {
t.Helper()
orig := common.LookupHost
diff --git a/internal/utility/mcp_call.go b/internal/mcp/client/mcp_call.go
similarity index 92%
rename from internal/utility/mcp_call.go
rename to internal/mcp/client/mcp_call.go
index bbe9f9cb2a..2ed234ad34 100644
--- a/internal/utility/mcp_call.go
+++ b/internal/mcp/client/mcp_call.go
@@ -14,7 +14,7 @@
// limitations under the License.
//
-package utility
+package mcpclient
import (
"context"
@@ -22,6 +22,7 @@ import (
"errors"
"fmt"
"net/http"
+ "ragflow/internal/utility"
"time"
)
@@ -38,6 +39,11 @@ type CallOptions struct {
Arguments json.RawMessage // JSON-encoded argument object
Timeout time.Duration
HTTPClient *http.Client
+ // AllowPrivateHosts relaxes the public-routability requirement so
+ // self-hosted MCP servers on private/docker networks work. Callers source
+ // it from the deployment flag (RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS); scheme
+ // validation, DNS resolution, and IP pinning still apply.
+ AllowPrivateHosts bool
}
// CallResult is the parsed tools/call response. The MCP spec
@@ -72,12 +78,12 @@ func CallTool(ctx context.Context, opts CallOptions) (*CallResult, error) {
if opts.Timeout <= 0 {
opts.Timeout = 10 * time.Second
}
- hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL)
+ hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL, opts.AllowPrivateHosts)
if err != nil {
return nil, err
}
if opts.HTTPClient == nil {
- opts.HTTPClient = PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)
+ opts.HTTPClient = utility.PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)
}
headers, headerErr := renderHeaders(opts.Headers, opts.Variables)
if headerErr != nil {
@@ -95,7 +101,7 @@ func CallTool(ctx context.Context, opts CallOptions) (*CallResult, error) {
case TransportSSE:
result, err := requestSSE(connectCtx, opts.URL, headers, opts.HTTPClient, "tools/call", map[string]any{
"name": opts.ToolName, "arguments": opts.Arguments,
- })
+ }, opts.AllowPrivateHosts)
if err != nil {
return nil, err
}
diff --git a/internal/utility/mcp_call_test.go b/internal/mcp/client/mcp_call_test.go
similarity index 99%
rename from internal/utility/mcp_call_test.go
rename to internal/mcp/client/mcp_call_test.go
index e2e9049780..0c21046ae1 100644
--- a/internal/utility/mcp_call_test.go
+++ b/internal/mcp/client/mcp_call_test.go
@@ -14,7 +14,7 @@
// limitations under the License.
//
-package utility
+package mcpclient
import (
"context"
diff --git a/internal/utility/mcp_client.go b/internal/mcp/client/mcp_client.go
similarity index 95%
rename from internal/utility/mcp_client.go
rename to internal/mcp/client/mcp_client.go
index 91fe3ff577..ae59edb0be 100644
--- a/internal/utility/mcp_client.go
+++ b/internal/mcp/client/mcp_client.go
@@ -14,7 +14,7 @@
// limitations under the License.
//
-// Package utility mcp client is a minimal Model Context Protocol (MCP) client used by
+// Package mcpclient is a minimal Model Context Protocol (MCP) client used by
// the Go MCP-management endpoints to list a remote server's tools during
// import and the "test" endpoint. It implements just enough of the spec to
// negotiate a session and call tools/list:
@@ -28,7 +28,7 @@
//
// The full Python implementation lives in common/mcp_tool_call_conn.py; this
// is a reduced port focused on tools/list discovery.
-package utility
+package mcpclient
import (
"bufio"
@@ -40,6 +40,7 @@ import (
"io"
"net/http"
"net/url"
+ "ragflow/internal/utility"
"strings"
"sync"
"time"
@@ -70,14 +71,19 @@ type Tool struct {
// FetchOptions controls a single tools/list discovery call.
type FetchOptions struct {
- URL string
- ServerType string
- Headers map[string]string
- Variables map[string]string
- Timeout time.Duration
- HTTPClient *http.Client
- pinHostname string
- pinIP string
+ URL string
+ ServerType string
+ Headers map[string]string
+ Variables map[string]string
+ Timeout time.Duration
+ HTTPClient *http.Client
+ // AllowPrivateHosts relaxes the public-routability requirement so
+ // self-hosted MCP servers on private/docker networks work. Callers source
+ // it from the deployment flag (RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS); scheme
+ // validation, DNS resolution, and IP pinning still apply.
+ AllowPrivateHosts bool
+ pinHostname string
+ pinIP string
}
// FetchTools opens a connection to the MCP server described by opts and
@@ -92,14 +98,14 @@ func FetchTools(ctx context.Context, opts FetchOptions) ([]Tool, error) {
opts.Timeout = 10 * time.Second
}
- hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL)
+ hostname, resolvedIP, err := AssertMCPURLSafe(opts.URL, opts.AllowPrivateHosts)
if err != nil {
return nil, err
}
opts.pinHostname = hostname
opts.pinIP = resolvedIP
if opts.HTTPClient == nil {
- opts.HTTPClient = PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)
+ opts.HTTPClient = utility.PinnedHTTPClient(hostname, resolvedIP, opts.Timeout)
}
headers, headerErr := renderHeaders(opts.Headers, opts.Variables)
@@ -114,7 +120,7 @@ func FetchTools(ctx context.Context, opts FetchOptions) ([]Tool, error) {
case TransportStreamableHTTP:
return fetchToolsStreamableHTTP(connectCtx, opts.URL, headers, opts.HTTPClient, opts.Timeout)
case TransportSSE:
- return fetchToolsSSE(connectCtx, opts.URL, headers, opts.HTTPClient)
+ return fetchToolsSSE(connectCtx, opts.URL, headers, opts.HTTPClient, opts.AllowPrivateHosts)
default:
return nil, fmt.Errorf("unsupported MCP server type: %s", opts.ServerType)
}
@@ -304,7 +310,7 @@ func terminateStreamableSessionBestEffort(ctx context.Context, client *http.Clie
return http.ErrUseLastResponse
}
- BestEffort("terminate MCP streamable HTTP session", func() error {
+ utility.BestEffort("terminate MCP streamable HTTP session", func() error {
req, err := http.NewRequestWithContext(cleanupCtx, http.MethodDelete, endpoint, nil)
if err != nil {
return fmt.Errorf("build MCP session termination request: %w", err)
@@ -405,8 +411,8 @@ func streamableSend(ctx context.Context, client *http.Client, endpoint, sessionI
// ---------- SSE transport ----------
-func fetchToolsSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client) ([]Tool, error) {
- result, err := requestSSE(ctx, endpoint, headers, client, "tools/list", nil)
+func fetchToolsSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client, allowPrivateHosts bool) ([]Tool, error) {
+ result, err := requestSSE(ctx, endpoint, headers, client, "tools/list", nil, allowPrivateHosts)
if err != nil {
return nil, err
}
@@ -414,7 +420,7 @@ func fetchToolsSSE(ctx context.Context, endpoint string, headers map[string]stri
}
// requestSSE initializes a session and performs one JSON-RPC request.
-func requestSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client, method string, params any) (json.RawMessage, error) {
+func requestSSE(ctx context.Context, endpoint string, headers map[string]string, client *http.Client, method string, params any, allowPrivateHosts bool) (json.RawMessage, error) {
streamReq, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
if err != nil {
return nil, fmt.Errorf("build SSE request: %w", err)
@@ -455,11 +461,11 @@ func requestSSE(ctx context.Context, endpoint string, headers map[string]string,
// Private targets are accepted only when they match the configured
// SSE endpoint host, preventing unrelated internal redirection.
postClient := client
- if postHost, postIP, vErr := AssertMCPURLSafeSameOrigin(postURL, endpoint); vErr != nil {
+ if postHost, postIP, vErr := AssertMCPURLSafeSameOrigin(postURL, endpoint, allowPrivateHosts); vErr != nil {
return nil, vErr
} else if u, perr := url.Parse(postURL); perr == nil && u.Hostname() != "" {
- if u.Hostname() != originalHost(endpoint) {
- postClient = PinnedHTTPClient(postHost, postIP, sseTimeoutFrom(ctx))
+ if !strings.EqualFold(u.Hostname(), originalHost(endpoint)) {
+ postClient = utility.PinnedHTTPClient(postHost, postIP, sseTimeoutFrom(ctx))
}
}
diff --git a/internal/utility/mcp_client_test.go b/internal/mcp/client/mcp_client_test.go
similarity index 99%
rename from internal/utility/mcp_client_test.go
rename to internal/mcp/client/mcp_client_test.go
index d24f5d3571..c93ee16cfc 100644
--- a/internal/utility/mcp_client_test.go
+++ b/internal/mcp/client/mcp_client_test.go
@@ -14,7 +14,7 @@
// limitations under the License.
//
-package utility
+package mcpclient
import (
"encoding/json"
diff --git a/internal/utility/mcp_ssrf.go b/internal/mcp/client/mcp_ssrf.go
similarity index 55%
rename from internal/utility/mcp_ssrf.go
rename to internal/mcp/client/mcp_ssrf.go
index fa227f492a..2cc63ee8c2 100644
--- a/internal/utility/mcp_ssrf.go
+++ b/internal/mcp/client/mcp_ssrf.go
@@ -14,19 +14,45 @@
// limitations under the License.
//
-package utility
+package mcpclient
import (
"net/url"
"ragflow/internal/common"
- "ragflow/internal/server"
"strings"
)
+// effectivePort returns the explicit port, or the scheme's default port when
+// omitted, so http://h and http://h:80 are treated as the same origin.
+func effectivePort(u *url.URL) string {
+ if p := u.Port(); p != "" {
+ return p
+ }
+ switch strings.ToLower(u.Scheme) {
+ case "http":
+ return "80"
+ case "https":
+ return "443"
+ }
+ return ""
+}
+
+// sameOrigin reports whether two URLs share scheme, port, and host. DNS
+// hostnames are case-insensitive, so the hostname is compared with
+// strings.EqualFold; scheme is already lowercased by url.Parse and compared
+// case-insensitively for safety; port is normalized so the default-port form
+// (http://h) and the explicit form (http://h:80) match.
+func sameOrigin(a, b *url.URL) bool {
+ return strings.EqualFold(a.Scheme, b.Scheme) &&
+ effectivePort(a) == effectivePort(b) &&
+ strings.EqualFold(a.Hostname(), b.Hostname())
+}
+
// AssertMCPURLSafe validates an MCP server URL. It delegates to
-// common.AssertURLSafe by default. When the deployment sets
-// RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS=true (a deployment-level operator decision),
-// the public-routability requirement is relaxed so self-hosted MCP servers on
+// common.AssertURLSafe by default. When allowPrivateHosts is true (a
+// deployment-level operator decision, sourced from
+// RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS at the call site), the
+// public-routability requirement is relaxed so self-hosted MCP servers on
// private/docker networks work — scheme validation, DNS resolution, and
// connection pinning to the resolved IP still apply.
//
@@ -34,10 +60,9 @@ import (
// direct tool calls). For URLs advertised by an SSE endpoint event, use
// AssertMCPURLSafeSameOrigin so a malicious server cannot redirect POSTs to an
// unrelated internal host.
-func AssertMCPURLSafe(rawURL string) (hostname, resolvedIP string, err error) {
- globalConfig := server.GetConfig()
+func AssertMCPURLSafe(rawURL string, allowPrivateHosts bool) (hostname, resolvedIP string, err error) {
hostname, resolvedIP, err = common.AssertURLSafe(rawURL)
- if err == nil || !globalConfig.GetMCPAllowPrivateHosts() {
+ if err == nil || !allowPrivateHosts {
return hostname, resolvedIP, err
}
strictErr := err
@@ -58,16 +83,15 @@ func AssertMCPURLSafe(rawURL string) (hostname, resolvedIP string, err error) {
// AssertMCPURLSafeSameOrigin validates a server-advertised URL (e.g., the POST
// URL from an SSE endpoint event). Public URLs are accepted. Private URLs are
-// accepted only when RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS is enabled AND the
-// advertised host matches originURL's host, so the server cannot bounce POSTs
-// to an unrelated internal target.
-func AssertMCPURLSafeSameOrigin(rawURL, originURL string) (hostname, resolvedIP string, err error) {
+// accepted only when allowPrivateHosts is true AND the advertised URL shares the
+// same origin (scheme, port, and host) as originURL, so the server cannot bounce
+// POSTs to another service on the same host but a different port or scheme.
+func AssertMCPURLSafeSameOrigin(rawURL, originURL string, allowPrivateHosts bool) (hostname, resolvedIP string, err error) {
hostname, resolvedIP, err = common.AssertURLSafe(rawURL)
if err == nil {
return hostname, resolvedIP, nil
}
- globalConfig := server.GetConfig()
- if !globalConfig.GetMCPAllowPrivateHosts() {
+ if !allowPrivateHosts {
return "", "", err
}
origin, perr := url.Parse(strings.TrimSpace(originURL))
@@ -78,8 +102,8 @@ func AssertMCPURLSafeSameOrigin(rawURL, originURL string) (hostname, resolvedIP
if perr != nil {
return "", "", err
}
- if parsed.Hostname() != origin.Hostname() {
+ if !sameOrigin(parsed, origin) {
return "", "", err
}
- return AssertMCPURLSafe(rawURL)
+ return AssertMCPURLSafe(rawURL, allowPrivateHosts)
}
diff --git a/internal/mcp/client/mcp_ssrf_test.go b/internal/mcp/client/mcp_ssrf_test.go
new file mode 100644
index 0000000000..8b5a1bdaf8
--- /dev/null
+++ b/internal/mcp/client/mcp_ssrf_test.go
@@ -0,0 +1,160 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package mcpclient
+
+import (
+ "ragflow/internal/common"
+ "testing"
+)
+
+// stubLookupHost pins DNS resolution for the duration of a test without
+// touching the server config singleton — the allowPrivateHosts decision is
+// now an explicit parameter instead of a global read.
+func stubLookupHost(t *testing.T, ips []string) {
+ t.Helper()
+ original := common.LookupHost
+ common.LookupHost = func(string) ([]string, error) { return ips, nil }
+ t.Cleanup(func() { common.LookupHost = original })
+}
+
+func TestAssertMCPURLSafePrivateHostAllowed(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+
+ host, ip, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp", true)
+ if err != nil {
+ t.Fatalf("expected allowed private MCP host to pass, got %v", err)
+ }
+ if host != "navigo-mcp" || ip != "172.18.0.5" {
+ t.Fatalf("expected pinning to resolved IP, got host=%q ip=%q", host, ip)
+ }
+}
+
+func TestAssertMCPURLSafeRejectsPrivateHostWhenDisabled(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+
+ if _, _, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp", false); err == nil {
+ t.Fatal("expected private host to be rejected when allowPrivateHosts is false")
+ }
+}
+
+func TestAssertMCPURLSafePublicHostUnaffected(t *testing.T) {
+ stubLookupHost(t, []string{"93.184.216.34"})
+
+ host, ip, err := AssertMCPURLSafe("https://mcp.example.com/mcp", false)
+ if err != nil {
+ t.Fatalf("expected public MCP host to pass, got %v", err)
+ }
+ if host != "mcp.example.com" || ip != "93.184.216.34" {
+ t.Fatalf("unexpected host/ip: %q %q", host, ip)
+ }
+}
+
+func TestAssertMCPURLSafeSameOriginAllowsPrivateAdvertisedURL(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+
+ host, ip, err := AssertMCPURLSafeSameOrigin("http://navigo-mcp:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse", true)
+ if err != nil {
+ t.Fatalf("expected same-origin private advertised URL to pass, got %v", err)
+ }
+ if host != "navigo-mcp" || ip != "172.18.0.5" {
+ t.Fatalf("unexpected host/ip: %q %q", host, ip)
+ }
+}
+
+func TestAssertMCPURLSafeSameOriginRejectsCrossOriginPrivateAdvertisedURL(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.6"})
+
+ if _, _, err := AssertMCPURLSafeSameOrigin("http://other-internal:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse", true); err == nil {
+ t.Fatal("expected cross-origin private advertised URL to be rejected")
+ }
+}
+
+// ---- corner cases for the parameterized guards ----
+
+func TestAssertMCPURLSafeEmptyURL(t *testing.T) {
+ stubLookupHost(t, []string{"8.8.8.8"})
+ if _, _, err := AssertMCPURLSafe("", true); err == nil {
+ t.Fatal("expected empty URL to be rejected")
+ }
+}
+
+func TestAssertMCPURLSafeMalformedURL(t *testing.T) {
+ stubLookupHost(t, []string{"8.8.8.8"})
+ // Unparseable / scheme-less input must error, never panic.
+ if _, _, err := AssertMCPURLSafe("://nonsense", true); err == nil {
+ t.Fatal("expected malformed URL to be rejected")
+ }
+}
+
+func TestAssertMCPURLSafeUnsupportedSchemeRejectedEvenWhenPrivateAllowed(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+ // allowPrivateHosts relaxes routability, NOT the scheme check; a non
+ // http(s) scheme must still be rejected via the strict path.
+ if _, _, err := AssertMCPURLSafe("ftp://navigo-mcp:8765/mcp", true); err == nil {
+ t.Fatal("expected unsupported scheme to be rejected even with allowPrivateHosts")
+ }
+}
+
+func TestAssertMCPURLSafeSameOriginRejectsPrivateWhenDisabled(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+ // Same-origin relaxation is gated on allowPrivateHosts; when false a
+ // private advertised URL must be rejected even on the same origin.
+ if _, _, err := AssertMCPURLSafeSameOrigin("http://navigo-mcp:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse", false); err == nil {
+ t.Fatal("expected same-origin private advertised URL to be rejected when disabled")
+ }
+}
+
+func TestAssertMCPURLSafePrivateHostWithEmptyLookupRejected(t *testing.T) {
+ stubLookupHost(t, nil) // resolver returns no addresses
+ if _, _, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp", true); err == nil {
+ t.Fatal("expected empty DNS resolution to be rejected")
+ }
+}
+
+// Same host, different port must be rejected: an SSE server must not be able to
+// bounce an admitted POST to another service listening on the same host but a
+// different port.
+func TestAssertMCPURLSafeSameOriginRejectsDifferentPort(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+ if _, _, err := AssertMCPURLSafeSameOrigin(
+ "http://navigo-mcp:9000/mcp/messages",
+ "http://navigo-mcp:8080/mcp/sse", true); err == nil {
+ t.Fatal("expected same-host-different-port advertised URL to be rejected")
+ }
+}
+
+// Same host and port, different scheme must be rejected: http vs https is a
+// different origin and must not be accepted as same-origin.
+func TestAssertMCPURLSafeSameOriginRejectsDifferentScheme(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+ if _, _, err := AssertMCPURLSafeSameOrigin(
+ "https://navigo-mcp:8765/mcp/messages",
+ "http://navigo-mcp:8765/mcp/sse", true); err == nil {
+ t.Fatal("expected same-host-different-scheme advertised URL to be rejected")
+ }
+}
+
+// DNS hostnames are case-insensitive, so a server-advertised URL on the same
+// host spelled with a different case must still be accepted as same-origin.
+func TestAssertMCPURLSafeSameOriginAcceptsMixedCaseHost(t *testing.T) {
+ stubLookupHost(t, []string{"172.18.0.5"})
+ if _, _, err := AssertMCPURLSafeSameOrigin(
+ "http://Example.COM:8765/mcp/messages",
+ "http://example.com:8765/mcp/sse", true); err != nil {
+ t.Fatalf("expected mixed-case same-host advertised URL to be accepted, got %v", err)
+ }
+}
diff --git a/internal/server/config.go b/internal/server/config.go
index be68b1a5d6..149d7b7e07 100644
--- a/internal/server/config.go
+++ b/internal/server/config.go
@@ -169,6 +169,17 @@ func GetConfig() *config.Config {
return globalConfig
}
+// MCPAllowPrivateHosts reports whether self-hosted MCP servers on private
+// networks are permitted (RAGFLOW_MCP_ALLOW_PRIVATE_HOSTS). It is nil-safe:
+// an uninitialized global config yields false so callers fail closed instead
+// of panicking on a nil *config.Config.
+func MCPAllowPrivateHosts() bool {
+ if globalConfig == nil {
+ return false
+ }
+ return globalConfig.GetMCPAllowPrivateHosts()
+}
+
// GetAllConfigs collects backend connection settings for administrator inspection.
// ExportConfigs intentionally retains plaintext credentials; the admin configuration
// endpoint restricts access to superusers, while PrintAll masks credentials in logs.
diff --git a/internal/server/mcp_allow_private_hosts_test.go b/internal/server/mcp_allow_private_hosts_test.go
new file mode 100644
index 0000000000..cfd5cdd335
--- /dev/null
+++ b/internal/server/mcp_allow_private_hosts_test.go
@@ -0,0 +1,33 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package server
+
+import "testing"
+
+// TestMCPAllowPrivateHostsNilConfigFailsClosed guards the nil-safe accessor:
+// when the global config has not been initialized (e.g. unit tests that never
+// call Init), reading the MCP private-hosts flag must fail closed (false)
+// instead of panicking on a nil *config.Config.
+func TestMCPAllowPrivateHostsNilConfigFailsClosed(t *testing.T) {
+ orig := globalConfig
+ globalConfig = nil
+ t.Cleanup(func() { globalConfig = orig })
+
+ if MCPAllowPrivateHosts() {
+ t.Fatal("expected nil global config to fail closed (false)")
+ }
+}
diff --git a/internal/service/mcp.go b/internal/service/mcp.go
index 9d6ce8b905..4fd8bcab41 100644
--- a/internal/service/mcp.go
+++ b/internal/service/mcp.go
@@ -30,9 +30,10 @@ import (
"ragflow/internal/common"
"ragflow/internal/dao"
"ragflow/internal/entity"
+ mcpclient "ragflow/internal/mcp/client"
"ragflow/internal/permission"
permissionresponse "ragflow/internal/permission/response"
- "ragflow/internal/utility"
+ "ragflow/internal/server"
)
const (
@@ -198,12 +199,13 @@ func fetchMCPTools(ctx context.Context, url, serverType string, headers, variabl
}
timeout := time.Duration(timeoutSeconds * float64(time.Second))
- tools, err := utility.FetchTools(ctx, utility.FetchOptions{
- URL: url,
- ServerType: serverType,
- Headers: jsonMapHeaderValues(headers),
- Variables: jsonMapStringValues(variables),
- Timeout: timeout,
+ tools, err := mcpclient.FetchTools(ctx, mcpclient.FetchOptions{
+ URL: url,
+ ServerType: serverType,
+ Headers: jsonMapHeaderValues(headers),
+ Variables: jsonMapStringValues(variables),
+ Timeout: timeout,
+ AllowPrivateHosts: server.MCPAllowPrivateHosts(),
})
if err != nil {
return nil, err
@@ -760,12 +762,13 @@ func (s *MCPService) ImportServers(ctx context.Context, userID string, servers m
stringVars := jsonMapStringValues(entity.JSONMap(variables))
mcpCtx, cancel := context.WithTimeout(ctx, timeout)
- tools, fetchErr := utility.FetchTools(mcpCtx, utility.FetchOptions{
- URL: url,
- ServerType: stype,
- Headers: headers,
- Variables: stringVars,
- Timeout: timeout,
+ tools, fetchErr := mcpclient.FetchTools(mcpCtx, mcpclient.FetchOptions{
+ URL: url,
+ ServerType: stype,
+ Headers: headers,
+ Variables: stringVars,
+ Timeout: timeout,
+ AllowPrivateHosts: server.MCPAllowPrivateHosts(),
})
cancel()
if fetchErr != nil {
@@ -853,7 +856,7 @@ func (s *MCPService) TestServer(ctx context.Context, userID, mcpID string, req *
// ErrMCPInvalidURL data errors instead of being swallowed inside the
// generic FetchTools error and re-classified by the handler as a 500.
// FetchTools repeats the check internally; the second call is cheap.
- if _, _, err := utility.AssertMCPURLSafe(req.URL); err != nil {
+ if _, _, err := mcpclient.AssertMCPURLSafe(req.URL, server.MCPAllowPrivateHosts()); err != nil {
return nil, fmt.Errorf("%w: %w", ErrMCPInvalidURL, err)
}
@@ -873,12 +876,13 @@ func (s *MCPService) TestServer(ctx context.Context, userID, mcpID string, req *
mcpCtx, cancel := context.WithTimeout(ctx, timeout)
defer cancel()
- tools, err := utility.FetchTools(mcpCtx, utility.FetchOptions{
- URL: req.URL,
- ServerType: req.ServerType,
- Headers: headers,
- Variables: vars,
- Timeout: timeout,
+ tools, err := mcpclient.FetchTools(mcpCtx, mcpclient.FetchOptions{
+ URL: req.URL,
+ ServerType: req.ServerType,
+ Headers: headers,
+ Variables: vars,
+ Timeout: timeout,
+ AllowPrivateHosts: server.MCPAllowPrivateHosts(),
})
if err != nil {
return nil, fmt.Errorf("%w: Test MCP error (id=%s): %w", ErrMCPTestFailed, mcpID, err)
@@ -902,7 +906,7 @@ func (s *MCPService) TestServer(ctx context.Context, userID, mcpID string, req *
return out, nil
}
-func toolsAsMap(tools []utility.Tool) map[string]interface{} {
+func toolsAsMap(tools []mcpclient.Tool) map[string]interface{} {
m := map[string]interface{}{}
for _, t := range tools {
if t.Raw != nil {
diff --git a/internal/utility/mcp_ssrf_test.go b/internal/utility/mcp_ssrf_test.go
deleted file mode 100644
index a8d92511f3..0000000000
--- a/internal/utility/mcp_ssrf_test.go
+++ /dev/null
@@ -1,90 +0,0 @@
-//
-// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
-
-package utility
-
-import (
- "ragflow/internal/common"
- "ragflow/internal/server"
- "testing"
-)
-
-func stubLookupHost(t *testing.T, ips []string) {
- t.Helper()
- original := common.LookupHost
- common.LookupHost = func(string) ([]string, error) { return ips, nil }
- t.Cleanup(func() { common.LookupHost = original })
- err := server.Init("")
- if err != nil {
- t.Fatalf("failed to init server: %v", err)
- }
-}
-
-func TestAssertMCPURLSafePrivateHostAllowed(t *testing.T) {
- t.Setenv(common.EnvMCPAllowPrivateHosts, "true")
- stubLookupHost(t, []string{"172.18.0.5"})
-
- host, ip, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp")
- if err != nil {
- t.Fatalf("expected allowed private MCP host to pass, got %v", err)
- }
- if host != "navigo-mcp" || ip != "172.18.0.5" {
- t.Fatalf("expected pinning to resolved IP, got host=%q ip=%q", host, ip)
- }
-}
-
-func TestAssertMCPURLSafeRejectsPrivateHostWhenDisabled(t *testing.T) {
- t.Setenv(common.EnvMCPAllowPrivateHosts, "")
- stubLookupHost(t, []string{"172.18.0.5"})
-
- if _, _, err := AssertMCPURLSafe("http://navigo-mcp:8765/mcp"); err == nil {
- t.Fatal("expected private host to be rejected when disabled")
- }
-}
-
-func TestAssertMCPURLSafePublicHostUnaffected(t *testing.T) {
- stubLookupHost(t, []string{"93.184.216.34"})
-
- host, ip, err := AssertMCPURLSafe("https://mcp.example.com/mcp")
- if err != nil {
- t.Fatalf("expected public MCP host to pass, got %v", err)
- }
- if host != "mcp.example.com" || ip != "93.184.216.34" {
- t.Fatalf("unexpected host/ip: %q %q", host, ip)
- }
-}
-
-func TestAssertMCPURLSafeSameOriginAllowsPrivateAdvertisedURL(t *testing.T) {
- t.Setenv(common.EnvMCPAllowPrivateHosts, "true")
- stubLookupHost(t, []string{"172.18.0.5"})
-
- host, ip, err := AssertMCPURLSafeSameOrigin("http://navigo-mcp:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse")
- if err != nil {
- t.Fatalf("expected same-origin private advertised URL to pass, got %v", err)
- }
- if host != "navigo-mcp" || ip != "172.18.0.5" {
- t.Fatalf("unexpected host/ip: %q %q", host, ip)
- }
-}
-
-func TestAssertMCPURLSafeSameOriginRejectsCrossOriginPrivateAdvertisedURL(t *testing.T) {
- t.Setenv(common.EnvMCPAllowPrivateHosts, "true")
- stubLookupHost(t, []string{"172.18.0.6"})
-
- if _, _, err := AssertMCPURLSafeSameOrigin("http://other-internal:8765/mcp/messages", "http://navigo-mcp:8765/mcp/sse"); err == nil {
- t.Fatal("expected cross-origin private advertised URL to be rejected")
- }
-}