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
54 changes: 32 additions & 22 deletions docs/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -116,11 +116,7 @@ Then, assuming you have a `stackql` MCP server serving streamable HTTP on port `
## **must** supply <provider>, <service>, <resource>
./build/stackql_mcp_client exec --client-type=http --url=http://127.0.0.1:9992 --exec.action list_methods --exec.args '{"provider": "google", "service": "compute", "resource": "networks"}'

## Describe a resource's output fields.
## **must** supply <provider>, <service>, <resource>
./build/stackql_mcp_client exec --client-type=http --url=http://127.0.0.1:9992 --exec.action describe_resource --exec.args '{"provider": "google", "service": "compute", "resource": "networks"}'

## Describe a single method's I/O contract (always EXTENDED).
## Describe a single method's I/O contract (always EXTENDED): inputs with param_type and the output fields.
## **must** supply <provider>, <service>, <resource>, <method>
./build/stackql_mcp_client exec --client-type=http --url=http://127.0.0.1:9992 --exec.action describe_method --exec.args '{"provider": "google", "service": "compute", "resource": "networks", "method": "get"}'

Expand All @@ -145,7 +141,7 @@ Then, assuming you have a `stackql` MCP server serving streamable HTTP on port `

## Canonical agent tools

The server publishes 14 tools. Each returns both rendered text (for the LLM) and a typed structured payload (for programmatic clients). Rendering is fixed per tool: a markdown table for uniform multi-row results, a markdown KV block for sparse / single-record / mixed-shape results.
The server publishes 15 tools. Each returns both rendered text (for the LLM) and a typed structured payload (for programmatic clients). Rendering is fixed per tool: a markdown table for uniform multi-row results, a markdown KV block for sparse / single-record / mixed-shape results.

Tools also carry MCP behavioural annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), derived from the same policy-gate classification that enforces the server [mode](#server-modes): statically read-only tools claim `readOnlyHint`, mutation/lifecycle tools claim `destructiveHint`, and SQL-carrying tools make no read-only claim because their effect depends on the submitted statement. Annotations are advisory hints for client UX; enforcement always remains with the policy gate.

Expand All @@ -155,16 +151,17 @@ Tools also carry MCP behavioural annotations (`readOnlyHint`, `destructiveHint`,
| `list_providers` | Table | Available cloud/SaaS providers (top of the hierarchy). No inputs. |
| `list_services` | Table | Services under a provider. Requires `provider`. |
| `list_resources` | Table | Resources under a `provider`.`service`. Requires `provider` and `service`. |
| `list_methods` | Table | Access methods (HTTP operations) for a resource. **Call before writing any query.** Requires `provider`, `service`, `resource`. |
| `describe_resource` | KV | Output fields for a resource's primary read method. Requires `provider`, `service`, `resource`. |
| `describe_method` | KV | Full I/O contract for one method (always EXTENDED). Requires `provider`, `service`, `resource`, `method`. |
| `list_methods` | Table | Access methods (HTTP operations) for a resource with their SQL verb and required params. **Call before writing any query.** Requires `provider`, `service`, `resource`. |
| `describe_method` | KV | Full I/O contract for one method (always EXTENDED): inputs with `param_type` and the `output` fields a SELECT can reference. Requires `provider`, `service`, `resource`, `method`. |
| `validate_select_query` | KV | Parse and plan a SELECT without executing. Returns `{valid, errors}`. SELECT only. |
| `run_select_query` | Table | Execute a SELECT. Returns `{rows}`. Reads only. |
| `run_mutation_query` | KV | Execute INSERT/UPDATE/REPLACE/DELETE. **Real side effects.** Returns `{messages, timestamp}`. Gated by the server [mode](#server-modes). |
| `run_lifecycle_operation` | KV | Execute a stackql `EXEC` lifecycle operation. Returns `{messages, timestamp}`. Gated by the server [mode](#server-modes). |
| `list_registry` | Table | Providers (and their versions) available in the configured registry. Optional `provider` lists versions for that provider. |
| `pull_provider` | KV | Install a provider from the registry into the local approot cache. Requires `provider`; `version` optional. Local cache write only. |
| `reload_credentials` | Table | Live-reload credentials: re-source the [`--env.file`](#credential-resourcing---envfile--reload_credentials) dotenv file into the process environment, invalidate cached auth contexts and report resolution status (with a `changed` flag) for every installed provider. Never returns secret values. Optional `provider` filters the report. Recovery and rotation only, never a pre-query step. Allowed in every mode. |
| `query_library_search` | Table | Search the curated query library by natural-language `intent` (optional `provider` / `service` / `tags` filters). Consult before composing SQL from scratch. Read-only, no credentials. |
| `query_library_get` | KV | Retrieve one library entry by `id`; with `params` the server validates them and returns rendered SQL plus the tool to execute it with. Read-only, no credentials. |

## Canonical agent prompts, resources and instructions

Expand Down Expand Up @@ -210,14 +207,38 @@ The server speaks every revision the [Go MCP SDK](https://github.com/modelcontex
Transport behaviour:

- **stdio** serves every revision on one process; a new-revision client's first request is served without a handshake and a legacy client's `initialize` still works.
- **Streamable HTTP** defaults to the stateful, session-per-client model (`Mcp-Session-Id`), which the SDK serves for revisions up to `2025-11-25`; a `2026-07-28` client learns that from `server/discover` and negotiates down, so existing HTTP hosts keep their sessions and elicitation unchanged. Set `"stateless": true` in `server` to serve `2026-07-28` natively: no `Mcp-Session-Id` is issued or read, `tools/list` / `prompts/list` / `resources/list` are connection-invariant, and gated writes use the input-required round trip. A sessionless server still accepts a legacy `initialize` and serves reads to that client, but cannot retain the elicitation capability a legacy client declared at initialise (the SDK gives each request an ephemeral session), so legacy HTTP clients cannot approve gated writes on it. Pick stateless for current-revision hosts, stateful for a mixed legacy fleet.
- **Streamable HTTP** defaults to the stateful, session-per-client model (`Mcp-Session-Id`), which the SDK serves for revisions up to `2025-11-25`; a `2026-07-28` request is answered with JSON-RPC error `-32022` (`UnsupportedProtocolVersion`, SDK v1.8.0; a plain HTTP 400 before) whose `data.supported` lists the handshake revisions, and `server/discover` advertises the same, so the client negotiates down and existing HTTP hosts keep their sessions and elicitation unchanged. Set `"stateless": true` in `server` (or pin `protocol_version` to `2026-07-28`, below) to serve `2026-07-28` natively: no `Mcp-Session-Id` is issued or read, `GET` and `DELETE` answer 405 (there is no session to tear down), `tools/list` / `prompts/list` / `resources/list` are connection-invariant, and gated writes use the input-required round trip. A sessionless server still accepts a legacy `initialize` and serves reads to that client, but cannot retain the elicitation capability a legacy client declared at initialise (the SDK gives each request an ephemeral session), so legacy HTTP clients cannot approve gated writes on it. Pick stateless for current-revision hosts, stateful for a mixed legacy fleet.

```bash
./build/stackql mcp --mcp.server.type=http --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9992", "stateless": true} }'
```

The server holds no cross-call state: mode, audit and provider auth are process-level configuration, so nothing needed to move behind explicit handles (SEP-2567). The robot suite drives stdio and both HTTP models with a 2025-06-18 handshake client and a 2026-07-28 stateless client, including the gated write on each revision.

### Pinning the revision (`--mcp.protocol.version`)

By default the server advertises every revision the SDK supports and negotiates per client. To narrow that:

```bash
./build/stackql mcp --mcp.server.type=http --mcp.protocol.version=2026-07-28 --mcp.config '{"server": {"transport": "http", "address": "127.0.0.1:9992"} }'
./build/stackql mcp --mcp.server.type=stdio --mcp.protocol.version=2025-11-25
```

The flag overrides `server.protocol_version` in `mcp.config` (`"server": {"protocol_version": "2025-11-25"}`) and sets the newest revision the server advertises (the SDK's `ServerOptions.SupportedProtocolVersions`):

| Value | Advertised | Effect |
|---|---|---|
| `auto` (default) or absent | every SDK revision | negotiation as above: the highest revision both sides speak |
| `2026-07-28` | `2026-07-28` only | sessionless only; implies `stateless` for Streamable HTTP. A legacy `initialize` is answered with `2025-11-25`, the SDK's cue that the client should disconnect rather than read the answer as the new lifecycle |
| `2025-11-25` (or any older revision) | that revision and everything before it | handshake lifecycle only: a `2026-07-28` request gets `-32022` with `data.supported` listing the advertised revisions so the client can renegotiate; older handshake clients keep their own revision |

Any other value fails config validation at startup (`invalid server.protocol_version`, naming the legal values). The robot suite covers each row on stdio and Streamable HTTP, the automatic negotiation, and the stateful downgrade error.

### Transport limits and deprecated features (SDK v1.8.0)

- Streamable HTTP request bodies are capped at the SDK default of 4 MiB (`413` beyond it) and JSON nested deeper than 1000 levels is rejected before parsing; stackql's own stdio transport bounds a frame at 8 MiB (issue #701). None of these are configurable in `mcp.config`: they sit far above any SQL statement stackql accepts.
- Roots, sampling and server-side logging are deprecated by `2026-07-28` (SEP-2577). stackql uses none of them: it issues no roots or sampling requests and emits no `notifications/message`; the SDK's default `logging` capability stays advertised for the deprecation window.

### Breaking change vs PR1

PR1 had a single `read_only: true/false` flag with a default of "no enforcement; mutations proceed." PR2 replaces that flag with `mode: safe` as the default, which means **mutations now require user approval out of the box.** Operators running an elicitation-capable client see one approval prompt per mutation. Operators running automation or the bundled client must explicitly opt into `full_access`.
Expand All @@ -239,7 +260,7 @@ Recorded per event:
| `decision` | `allow` / `refuse_immediate` / `needs_approval_accepted` / `needs_approval_declined` / `needs_approval_cancelled` / `needs_approval_unavailable` |
| `query_class` | `select` / `mutation_create` / `mutation_delete` / `lifecycle` / `unknown` |
| `sql` | For query tools (`run_select_query`, `run_mutation_query`, `run_lifecycle_operation`, `validate_select_query`) |
| `args` | Hierarchy fields for metadata tools (`list_*`, `describe_*`); SQL + row_limit for query tools |
| `args` | Hierarchy fields for metadata tools (`list_*`, `describe_method`); SQL + row_limit for query tools |
| `duration_ms` | Wall-clock duration of the gate + handler |
| `error` | Error message if the tool errored or was refused |

Expand Down Expand Up @@ -391,17 +412,6 @@ $ ./build/stackql_mcp_client exec --client-type=http --url=http://127.0.0.1:999
}


$ ./build/stackql_mcp_client exec --client-type=http --url=http://127.0.0.1:9992 --exec.action describe_resource --exec.args '{"provider": "google", "service": "compute", "resource": "networks"}' 2>/dev/null | jq
{
"rows": [
{ "name": "id", "type": "string" },
{ "name": "name", "type": "string" },
{ "name": "description", "type": "string" },
{ "name": "selfLink", "type": "string" }
]
}


$ ./build/stackql_mcp_client exec --client-type=http --url=http://127.0.0.1:9992 --exec.action describe_method --exec.args '{"provider": "google", "service": "compute", "resource": "networks", "method": "get"}' 2>/dev/null | jq
{
"rows": [
Expand Down
2 changes: 1 addition & 1 deletion go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ require (
github.com/jackc/pgx/v5 v5.9.2
github.com/lib/pq v1.10.4
github.com/magiconair/properties v1.8.6
github.com/modelcontextprotocol/go-sdk v1.7.0
github.com/modelcontextprotocol/go-sdk v1.8.0
github.com/olekukonko/tablewriter v0.0.0-20180130162743-b8a9be070da4
github.com/sirupsen/logrus v1.9.3
github.com/snowflakedb/gosnowflake v1.15.0
Expand Down
4 changes: 2 additions & 2 deletions go.sum
Original file line number Diff line number Diff line change
Expand Up @@ -293,8 +293,8 @@ github.com/minio/c2goasm v0.0.0-20190812172519-36a3d3bbc4f3 h1:+n/aFZefKZp7spd8D
github.com/minio/c2goasm v0.0.0-20190812172519-36a3d3bbc4f3/go.mod h1:RagcQ7I8IeTMnF8JTXieKnO4Z6JCsikNEzj0DwauVzE=
github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
github.com/modelcontextprotocol/go-sdk v1.7.0 h1:yqjY2dsbKAC0LSuWZVBMrHgiG8ukXv6NRo0JiALay44=
github.com/modelcontextprotocol/go-sdk v1.7.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
github.com/modelcontextprotocol/go-sdk v1.8.0 h1:KIvahhYqwtbeniWVPs3TcXEA7b8jEtwfBpOTAI+Urx4=
github.com/modelcontextprotocol/go-sdk v1.8.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
github.com/mtibben/percent v0.2.1 h1:5gssi8Nqo8QU/r2pynCm+hBQHpkB/uNK7BJCFogWdzs=
github.com/mtibben/percent v0.2.1/go.mod h1:KG9uO+SZkUp+VkRHsCdYQV3XSZrrSpR3O9ibNBTZrns=
github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
Expand Down
12 changes: 8 additions & 4 deletions internal/stackql/cmd/mcp.go
Original file line number Diff line number Diff line change
Expand Up @@ -82,10 +82,11 @@ func providerRegistryIdentifier(runtimeCtx dto.RuntimeCtx) string {

//nolint:gochecknoglobals // cobra pattern
var (
mcpServerType string // overwritten by flag
mcpConfig string // overwritten by flag
mcpLogFormat string // overwritten by flag; audit log encoding (issue #729)
envFilePath string // overwritten by flag; sourced for every entrypoint in initConfig
mcpServerType string // overwritten by flag
mcpConfig string // overwritten by flag
mcpLogFormat string // overwritten by flag; audit log encoding (issue #729)
mcpProtocolVersion string // overwritten by flag; revision ceiling (issue #784)
envFilePath string // overwritten by flag; sourced for every entrypoint in initConfig
)

//nolint:gochecknoglobals // cobra pattern
Expand Down Expand Up @@ -152,6 +153,9 @@ func runMCPServer(handlerCtx handler.HandlerContext) {
if mcpLogFormat != "" {
config.Server.Audit.Format = mcpLogFormat
}
if mcpProtocolVersion != "" {
config.Server.ProtocolVersion = mcpProtocolVersion
}
// MCP clients must be able to distinguish "query ran, zero rows" from
// "query failed upstream" (issue #670), so data acquisition failures
// surface as statement errors rather than empty result sets. This is
Expand Down
1 change: 1 addition & 0 deletions internal/stackql/cmd/root.go
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,7 @@ func init() {
rootCmd.PersistentFlags().StringVar(&mcpConfig, "mcp.config", "{}", "MCP server config file path (YAML or JSON)")
rootCmd.PersistentFlags().StringVar(&mcpServerType, "mcp.server.type", "", "MCP server type (http or stdio for now)")
rootCmd.PersistentFlags().StringVar(&mcpLogFormat, "mcp.log.format", "", "MCP audit log format: jsonl (default) or otel (OTLP/JSON log records); overrides server.audit.format in mcp.config")
rootCmd.PersistentFlags().StringVar(&mcpProtocolVersion, "mcp.protocol.version", "", "newest MCP protocol revision advertised: auto (default, every SDK revision), 2026-07-28 (sessionless only; implies stateless HTTP) or an older revision such as 2025-11-25 (that revision and earlier); overrides server.protocol_version in mcp.config")
rootCmd.PersistentFlags().StringVar(&envFilePath, "env.file", "", "optional dotenv-style file sourced into the process environment at startup, created empty if absent; the MCP reload_credentials tool re-sources it on demand")
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -184,14 +184,6 @@ func (b *stackqlMCPReverseProxyService) RunQueryJSON(ctx context.Context, input
return b.query(ctx, input.SQL, input.RowLimit)
}

func (b *stackqlMCPReverseProxyService) DescribeResource(ctx context.Context, hI dto.HierarchyInput) ([]map[string]interface{}, error) {
q, qErr := b.interrogator.GetDescribeResource(hI)
if qErr != nil {
return nil, qErr
}
return b.query(ctx, q, hI.RowLimit)
}

func (b *stackqlMCPReverseProxyService) DescribeMethod(ctx context.Context, hI dto.HierarchyInput) ([]map[string]interface{}, error) {
q, qErr := b.interrogator.GetDescribeMethod(hI)
if qErr != nil {
Expand Down
23 changes: 0 additions & 23 deletions internal/stackql/mcpbackend/mcp_service_stackql.go
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,6 @@ type StackqlInterrogator interface {
GetShowServices(dto.HierarchyInput, string) (string, error)
GetShowResources(dto.HierarchyInput, string) (string, error)
GetShowMethods(dto.HierarchyInput) (string, error)
GetDescribeResource(dto.HierarchyInput) (string, error)
GetDescribeMethod(dto.HierarchyInput) (string, error)
GetQueryJSON(dto.QueryJSONInput) (string, error)
GetRegistryList(provider string) (string, error)
Expand Down Expand Up @@ -168,20 +167,6 @@ func (s *simpleStackqlInterrogator) GetShowMethods(hI dto.HierarchyInput) (strin
return sb.String(), nil
}

func (s *simpleStackqlInterrogator) GetDescribeResource(hI dto.HierarchyInput) (string, error) {
if hI.Provider == "" || hI.Service == "" || hI.Resource == "" {
return "", fmt.Errorf("provider, service and / or resource not specified")
}
sb := strings.Builder{}
sb.WriteString("DESCRIBE ")
sb.WriteString(hI.Provider)
sb.WriteString(".")
sb.WriteString(hI.Service)
sb.WriteString(".")
sb.WriteString(hI.Resource)
return sb.String(), nil
}

func (s *simpleStackqlInterrogator) GetDescribeMethod(hI dto.HierarchyInput) (string, error) {
if hI.Provider == "" || hI.Service == "" || hI.Resource == "" || hI.Method == "" {
return "", fmt.Errorf("provider, service, resource and / or method not specified")
Expand Down Expand Up @@ -510,14 +495,6 @@ func drainSQLRowStream(
}
}

func (b *stackqlMCPService) DescribeResource(ctx context.Context, hI dto.HierarchyInput) ([]map[string]interface{}, error) {
q, qErr := b.interrogator.GetDescribeResource(hI)
if qErr != nil {
return nil, qErr
}
return b.runPreprocessedQueryJSON(ctx, q, unlimitedRowLimit)
}

func (b *stackqlMCPService) DescribeMethod(ctx context.Context, hI dto.HierarchyInput) ([]map[string]interface{}, error) {
q, qErr := b.interrogator.GetDescribeMethod(hI)
if qErr != nil {
Expand Down
3 changes: 1 addition & 2 deletions packaging/mcpb/manifest/BUNDLE_README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,7 @@ enable it.
- `list_services` - list services within a provider
- `list_resources` - list resources within a service
- `list_methods` - list methods for a resource
- `describe_resource` - describe a resource's fields
- `describe_method` - describe a method's parameters
- `describe_method` - describe a method's parameters and output fields
- `validate_select_query` - validate a SELECT query without running it
- `run_select_query` - run a SELECT query against a provider
- `run_mutation_query` - run an INSERT/UPDATE/DELETE (provisioning) query
Expand Down
Loading
Loading