Skip to content
Merged
Show file tree
Hide file tree
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
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ require (
github.com/spf13/cobra v1.4.0
github.com/spf13/pflag v1.0.5
github.com/spf13/viper v1.10.1
github.com/stackql/any-sdk v0.5.2-beta03
github.com/stackql/any-sdk v0.5.2-beta04
github.com/stackql/go-suffix-map v0.0.1-alpha01
github.com/stackql/psql-wire v0.1.2-beta01
github.com/stackql/stackql-parser v0.0.16-alpha01
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -467,8 +467,8 @@ github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/viper v1.10.1 h1:nuJZuYpG7gTj/XqiUwg8bA0cp1+M2mC3J4g5luUYBKk=
github.com/spf13/viper v1.10.1/go.mod h1:IGlFPqhNAPKRxohIzWpI5QEy4kuI7tcl5WvR+8qy1rU=
github.com/stackql/any-sdk v0.5.2-beta03 h1:LuA5R6+973FJxH566Uk0OvliKQYq1qcDU4Y2l3OIy/M=
github.com/stackql/any-sdk v0.5.2-beta03/go.mod h1:ZRTGrcDKFLaC+5yWo4OqXVs1HTNxgYM9nQsQDlq0Fe0=
github.com/stackql/any-sdk v0.5.2-beta04 h1:GnXiDQCWF2VdSHbtw1b4EmaT/GtUdVq+Cr622p2p/98=
github.com/stackql/any-sdk v0.5.2-beta04/go.mod h1:ZRTGrcDKFLaC+5yWo4OqXVs1HTNxgYM9nQsQDlq0Fe0=
github.com/stackql/go-suffix-map v0.0.1-alpha01 h1:TDUDS8bySu41Oo9p0eniUeCm43mnRM6zFEd6j6VUaz8=
github.com/stackql/go-suffix-map v0.0.1-alpha01/go.mod h1:QAi+SKukOyf4dBtWy8UMy+hsXXV+yyEE4vmBkji2V7g=
github.com/stackql/psql-wire v0.1.2-beta01 h1:+0xeLLam3nbI1iv84pWJYGYw5VO5S/+eICRbdu6+dj8=
Expand Down
23 changes: 23 additions & 0 deletions pkg/mcp_server/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,29 @@ logging:
enable_request_logging: false
```

### Restricting Published Tools

The top-level `enabled_tools` field on `Config` controls which MCP tools the server publishes. It is an allowlist of tool names.

- **Omitted, `null`, or empty list** — every built-in tool is registered. This is the default and matches the historical behaviour.
- **Populated list** — only the named tools are registered. Any other tool is absent from `tools/list` and `tools/call` returns an `unknown tool` error.

This is enforced at registration time in `pkg/mcp_server/server.go` via the `addToolIfEnabled` helper, which consults `Config.IsToolEnabled(name)` before delegating to `mcp.AddTool`. There is no runtime cost for tools that are not enabled — they are never bound to the server.

JSON example — a single-purpose server that exposes only the liveness check:

```json
{
"server": {
"transport": "http",
"address": "127.0.0.1:9915"
},
"enabled_tools": ["greet"]
}
```

When the server is launched via the `stackql mcp` (or `stackql srv --mcp.server.type=...`) command, this field is parsed from the same `--mcp.config` JSON blob as the rest of the configuration — no additional flag is required. For example, `stackql mcp --mcp.config='{"server": { "transport": "http", "address": "127.0.0.1:9915"}, "enabled_tools": ["greet"]}'`.

## MCP Protocol Support

The server implements the Model Context Protocol specification and supports:
Expand Down
19 changes: 19 additions & 0 deletions pkg/mcp_server/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,25 @@ type Config struct {

// Backend contains backend-specific configuration.
Backend BackendConfig `json:"backend" yaml:"backend"`

// EnabledTools restricts which MCP tools the server publishes.
// When nil or empty, every built-in tool is published (default behavior).
// When populated, only the named tools are registered.
EnabledTools []string `json:"enabled_tools,omitempty" yaml:"enabled_tools,omitempty"`
}

// IsToolEnabled reports whether the named tool should be published.
// Empty/nil EnabledTools means all tools are enabled.
func (c *Config) IsToolEnabled(name string) bool {
if len(c.EnabledTools) == 0 {
return true
}
for _, n := range c.EnabledTools {
if n == name {
return true
}
}
return false
}

func (c *Config) GetServerTransport() string {
Expand Down
68 changes: 49 additions & 19 deletions pkg/mcp_server/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,17 @@ func (s *simpleMCPServer) runHTTPServer(server *mcp.Server, config *Config) erro
return nil
}

// addToolIfEnabled registers a tool only when cfg.IsToolEnabled allows it.
// This is the single chokepoint by which the EnabledTools allowlist is enforced.
func addToolIfEnabled[In, Out any](
s *mcp.Server, cfg *Config, t *mcp.Tool, h mcp.ToolHandlerFor[In, Out],
) {
if !cfg.IsToolEnabled(t.Name) {
return
}
mcp.AddTool(s, t, h)
}

func NewExampleBackendServer(config *Config, logger *logrus.Logger) (MCPServer, error) {
backend := NewExampleBackend("example-connection-string")
return newMCPServer(config, backend, logger)
Expand Down Expand Up @@ -114,8 +125,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
&mcp.Implementation{Name: "stackql", Version: "v0.1.1"},
nil,
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "greet",
Description: "Say hi. A simple liveness check.",
Expand All @@ -130,8 +142,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(bytesOut)}}}, out, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "server_info",
Description: "Get server information",
Expand All @@ -146,8 +159,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(bytesOut)}}}, out, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "db_identity",
Description: "get current database identity",
Expand All @@ -162,8 +176,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(bytesOut)}}}, out, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "query_v2",
Description: "Deprecated: Please switch to query_v3. Execute a SQL query. Please adhere to the expected parameters. Returns a textual response",
Expand All @@ -182,8 +197,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
}, nil, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "query_v3",
Description: "Execute a SQL query. Returns a DTO with rows or raw text.",
Expand All @@ -207,8 +223,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(bytesOut)}}}, out, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "query_json_v2",
Description: "Execute a SQL query and return a JSON array of rows, as text plus DTO.",
Expand All @@ -223,8 +240,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(bytesOut)}}}, out, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "validate_query_json_v2",
Description: "Validate a SQL SELECT query ahead of time and return a JSON object expressing success, or else an error. Supply the query exactly as you would execute it, no qualifying keywords. Only works for SELECT at this time.",
Expand All @@ -244,8 +262,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(bytesOut)}}}, out, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "exec_query_json_v2",
Description: "Exec query pattern; for non-read operations. Tread carefully!!! These are almost always mutations! Execute a SQL query and return an optional JSON object, describing the effect(s).",
Expand All @@ -259,8 +278,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
return &mcp.CallToolResult{Content: []mcp.Content{&mcp.TextContent{Text: string(bytesOut)}}}, res, nil
},
)
mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "query_validate_json_v2",
Description: "Run an ahead of time (AOT) check for query tractability.",
Expand All @@ -275,8 +295,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "prompt_write_safe_select_tool",
Description: "PLACEHOLDER Future proofing: prompt guidelines for writing safe SELECT queries.",
Expand All @@ -292,8 +313,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "list_tables_json",
Description: "List tables in a schema and return JSON rows.",
Expand All @@ -315,8 +337,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "list_tables_json_page",
Description: "Future proofing: List tables with pagination and filters, returns JSON.",
Expand All @@ -338,8 +361,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "list_providers",
Description: "List available providers. This is the top level of the stackql hierarchy.",
Expand All @@ -355,8 +379,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "list_services",
Description: "List services. **must** supply <provider>.",
Expand All @@ -372,8 +397,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "list_resources",
Description: "List available resources. **must** supply <provider>, <service>.",
Expand All @@ -389,8 +415,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "list_methods",
Description: "List access methods for a resource. Interrogating this is almost compulsory before executing a CRUD query; you will need to infer requireed WHERE parameters. **must** supply <provider>, <service>, <resource>.",
Expand All @@ -406,8 +433,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "describe_table",
Description: "PLACEHOLDER Future proofing: Get detailed information about a table.",
Expand All @@ -423,8 +451,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "get_foreign_keys",
Description: "PLACEHOLDER Future proofing: Get foreign key information for a table.",
Expand All @@ -440,8 +469,9 @@ func newMCPServer(config *Config, backend Backend, logger *logrus.Logger) (MCPSe
},
)

mcp.AddTool(
addToolIfEnabled(
server,
config,
&mcp.Tool{
Name: "find_relationships",
Description: "PLACEHOLDER Future proofing: Find explicit and implied relationships for a table.",
Expand Down
58 changes: 58 additions & 0 deletions test/robot/functional/mcp.robot
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,18 @@ Start MCP Servers
... 5446
... stdout=${CURDIR}${/}tmp${/}Stackql-MCP-Server-HTTPS.txt
... stderr=${CURDIR}${/}tmp${/}Stackql-MCP-Server-HTTPS-stderr.txt
Start Process ${STACKQL_EXE}
... mcp
... \-\-mcp.server.type\=http
... \-\-mcp.config
... {"server": {"transport": "http", "address": "127.0.0.1:9915"}, "enabled_tools": ["greet"] }
... \-\-registry
... ${REGISTRY_NO_VERIFY_CFG_JSON_STR}
... \-\-auth
... ${AUTH_CFG_STR}
... \-\-tls.allowInsecure
... stdout=${CURDIR}${/}tmp${/}Stackql-MCP-Server-Restricted.txt
... stderr=${CURDIR}${/}tmp${/}Stackql-MCP-Server-Restricted-stderr.txt
Sleep 5s

Parse MCP JSON Output
Expand Down Expand Up @@ -544,3 +556,49 @@ MCP HTTPS Server Exec Query Canonical
... stderr=${CURDIR}${/}tmp${/}MCP-HTTPS-Exec-Query-canonical-stderr.txt
${meta_rels_obj}= Parse MCP JSON Output ${meta_rels.stdout}
Dictionary Should Contain Key ${meta_rels_obj} timestamp

MCP HTTP Server Restricted Tools Allowlist
[Documentation] Verify enabled_tools in mcp.config restricts which tools are published.
... Server at 9915 is started with enabled_tools=["greet"]; only greet should be callable.
Pass Execution If "%{IS_SKIP_MCP_TEST=false}" == "true" Some platforms do not have the MCP client available
Sleep 5s
${list_result}= Run Process ${STACKQL_MCP_CLIENT_EXE}
... exec
... \-\-client\-type\=http
... \-\-url\=http://127.0.0.1:9915
... stdout=${CURDIR}${/}tmp${/}MCP-Restricted-list-tools.txt
... stderr=${CURDIR}${/}tmp${/}MCP-Restricted-list-tools-stderr.txt
Should Be Equal As Integers ${list_result.rc} 0
Should Contain ${list_result.stdout} greet
Should Not Contain ${list_result.stdout} server_info
Should Not Contain ${list_result.stdout} list_providers
Should Not Contain ${list_result.stdout} query_v2
${greet_result}= Run Process ${STACKQL_MCP_CLIENT_EXE}
... exec
... \-\-client\-type\=http
... \-\-url\=http://127.0.0.1:9915
... \-\-exec.action greet
... \-\-exec.args {"name": "RESTRICTED USER"}
... stdout=${CURDIR}${/}tmp${/}MCP-Restricted-greet.txt
... stderr=${CURDIR}${/}tmp${/}MCP-Restricted-greet-stderr.txt
Should Be Equal As Integers ${greet_result.rc} 0
Should Contain ${greet_result.stdout} RESTRICTED USER
${denied_result}= Run Process ${STACKQL_MCP_CLIENT_EXE}
... exec
... \-\-client\-type\=http
... \-\-url\=http://127.0.0.1:9915
... \-\-exec.action list_providers
... stdout=${CURDIR}${/}tmp${/}MCP-Restricted-list-providers.txt
... stderr=${CURDIR}${/}tmp${/}MCP-Restricted-list-providers-stderr.txt
Should Not Be Equal As Integers ${denied_result.rc} 0
Should Contain ${denied_result.stderr} unknown tool
${denied_query}= Run Process ${STACKQL_MCP_CLIENT_EXE}
... exec
... \-\-client\-type\=http
... \-\-url\=http://127.0.0.1:9915
... \-\-exec.action query_v2
... \-\-exec.args {"sql": "select 1;"}
... stdout=${CURDIR}${/}tmp${/}MCP-Restricted-query.txt
... stderr=${CURDIR}${/}tmp${/}MCP-Restricted-query-stderr.txt
Should Not Be Equal As Integers ${denied_query.rc} 0
Should Contain ${denied_query.stderr} unknown tool
Loading