6 posts tagged with "ai"

StackQL v0.11 is out. The StackQL MCP server: now includes the current Model Context Protocol revision, 2026-07-28, alongside every earlier revision it already supported, and the audit log that records what an agent did can be written as OpenTelemetry log records instead of the bespoke JSONL format. Both are available today through every install channel.

The StackQL MCP server is now available through every runtime an agent is likely to live in: prebuilt Claude Desktop bundles, npm, PyPI, Docker, a GitHub Action, and the Official MCP Registry. It is the same server in each case - one binary, pulled and launched the way your environment prefers.

What the StackQL MCP server is​

StackQL exposes cloud and SaaS providers - AWS, Google Cloud, Azure, GitHub, Kubernetes, Snowflake, Databricks and more - as a single SQL surface. The MCP server puts that surface in front of an AI agent: the agent discovers providers, services, resources and methods, then runs SELECT queries to read state and (when you allow it) INSERT / UPDATE / DELETE to change it. Reads and writes are gated by a server mode and recorded to an audit log, so "what the agent did" is always answerable.

For background on the protocol itself, see the original StackQL MCP Server Now Available post and the MCP command reference.

One server, every runtime​

Every channel runs the same stackql binary. Pick the one that matches your client:

A typical stdio client config is three lines. For npx:

{ "mcpServers": { "stackql": { "command": "npx", "args": ["-y", "@stackql/mcp-server"] } } }

Swap npx for uvx stackql-mcp-server or docker run -i --rm stackql/stackql-mcp and you have the Python or Docker form. The npm and PyPI launchers download the signed stackql binary on first run, verify its checksum, and share a single cache. The full matrix - including the manual claude_desktop_config.json form for an existing binary - is in Installing the MCP server.

The approvable MCP server​

Letting an agent touch your cloud is a trust decision, so the supply chain is built to be checkable:

• The embedded stackql binary is Authenticode-signed (Windows) and Apple-notarised (macOS).
• Every .mcpb bundle ships with a published SHA-256 checksum on the release page.
• The npm and PyPI launchers verify the downloaded binary's SHA-256 before first use.
• The MCP Registry entry attests the per-platform hashes, so a directory or marketplace can confirm what it is shipping.

On top of the supply chain, the server defaults to mode: safe - reads run freely, mutations and lifecycle operations need approval through the MCP elicitation flow. Pin read_only for inventory agents that should never write, or full_access for trusted automation. See Server modes.

A worked example: cloud audit in CI​

The GitHub Action is where the multi-vector story pays off. stackql/setup-stackql-mcp@v1 installs the binary and writes an MCP config (defaulting to read_only), and anthropics/claude-code-action consumes it through claude_args. The result is an agent that audits your AWS account on every run and files an issue with the SQL it used as evidence:

- id: stackql
  uses: stackql/setup-stackql-mcp@v1
  env:
    AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
  with:
    mode: read_only

- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: |
      Using the stackql tools, audit our AWS account for: S3 buckets without
      encryption or with public access, security groups open to 0.0.0.0/0 on
      sensitive ports, and IAM users without MFA. Open a GitHub issue
      "Cloud audit <date>" summarising findings WITH the SQL you ran as
      evidence. If nothing is found, do not open an issue.
    claude_args: |
      --mcp-config ${{ steps.stackql.outputs.mcp-config-file }}
      --allowedTools 'mcp__stackql__*'

Because the config is pinned to read_only, the audit can read everything and change nothing - the safety contract is enforced by the server, not by trust in the prompt. The action README has more recipes, including cost estimates on a pull request and a credential-free GitHub inventory.

What the agent actually sees​

Under the hood the agent works the StackQL hierarchy with the same tools whatever the runtime. Pulling the GitHub provider and listing its services looks like this:

> pull_provider {"provider": "github"}
github provider, version 'v26.05.00393' successfully installed

> list_services {"provider": "github"}
actions, activity, apps, billing, checks, code_scanning, codespaces,
copilot, dependabot, gists, git, issues, orgs, packages, projects,
pulls, repos, search, secret_scanning, teams, users, ...

From there the agent can call list_resources and list_methods to discover the required WHERE parameters, then run_select_query to answer a question like "how many public repositories does the stackql org have?" - all without anyone hand-writing SQL.

Get started​

• Install docs for every channel: Installing the MCP server
• Command reference, modes and audit log: stackql mcp
• Registry entry: io.github.stackql/stackql-mcp
• Source and releases: github.com/stackql/stackql

⭐ Star us on GitHub and tell us what your agents build.

We've released the latest version of the StackQL Cloudflare provider, including the full Cloudflare V4 API surface under SQL with 108 services, 1259 resources, and 2840 operations.

Service highlights​

Key services in this release include:

Authentication​

Authenticate with a Cloudflare API token via the CLOUDFLARE_API_TOKEN environment variable:

export CLOUDFLARE_API_TOKEN=...

Example queries​

List your zones:

SELECT id, name, status, plan
FROM cloudflare.zones.zones
WHERE account.id = '<account_id>';

Inspect Workers scripts in an account:

SELECT id, modified_on, usage_model
FROM cloudflare.workers.scripts
WHERE account_id = '<account_id>';

List DNS records for a zone:

SELECT name, type, content, ttl, proxied
FROM cloudflare.dns.records
WHERE zone_id = '<zone_id>';

Pull a Radar BGP summary:

SELECT *
FROM cloudflare.radar.routes_stats;

Binary and non-JSON responses​

A number of Cloudflare endpoints return binary or plain-text payloads - PDF LOAs, PNG screenshots, raw script source, CSV exports. The provider wraps these as a one-row table with a contents column so they're still SELECT-able:

SELECT contents
FROM cloudflare.browser_rendering.screenshot
WHERE account_id = '<account_id>' AND url = 'https://example.com';

Get started​

Pull the provider from the public registry:

registry pull cloudflare

Then start querying. Let us know what you build. Star us on GitHub.

We've published a Claude Skill for StackQL provider development. It provides Claude with the context needed to help you build providers using the any-sdk library (interface used by StackQL to interact with the cloud providers).

What's in the Skill​

The skill covers the full provider development workflow:

• Provider document structure - The provider.yaml schema and service document layout
• OpenAPI extensions - All x-stackQL-* extensions including x-stackQL-resources, x-stackQL-config, x-stackQL-objectKey, and others
• Resource and method definitions - How to define resources, map methods to operations, and configure responses
• SQL verb mappings - Connecting REST operations to SELECT, INSERT, UPDATE, and DELETE
• Authentication patterns - API keys, service accounts, OAuth, and custom auth schemes
• Pagination handling - Request/response token configuration
• Response processing - JSONPath extraction, transformations, and schema handling

Download​

Grab the skill from the any-sdk repository:

Download stackql-provider-development.md

Usage​

With the skill loaded, you can ask Claude things like:

• "Create a provider definition for this API"
• "How do I map this endpoint to a SELECT operation?"
• "What's the correct objectKey syntax for this nested response?"
• "Help me configure pagination for this API"

Claude will have the full context of StackQL's OpenAPI extensions and provider patterns to work from.

Example​

Here's a sample interaction after loading the skill:

You: I have an API endpoint GET /users that returns {"data": {"users": [...]}}. 
     How do I set up the resource?

Claude: For that response structure, you'd configure the method like this:

methods:
  list:
    operation:
      $ref: '#/paths/~1users/get'
    response:
      mediaType: application/json
      openAPIDocKey: '200'
      objectKey: $.data.users

The objectKey uses JSONPath to extract the users array from the nested response.

Resources​

• StackQL Provider Registry
• any-sdk documentation
• StackQL documentation

⭐ Star us on GitHub

pystackql now includes a markdownkv output format optimized for LLM processing of control plane and data plane data from cloud providers.

Background​

Recent research from ImprovingAgents.com tested 11 data formats to determine which ones LLMs parse most accurately. Using 1,000 synthetic employee records and 1,000 randomized queries, they measured how well different formats preserved data integrity through LLM processing.

The results:

Markdown-KV showed a 37% improvement over CSV and 16 percentage points over JSON. The tradeoff: it uses approximately 2.7x more tokens than CSV.

What is Markdown-KV?​

Markdown-KV uses hierarchical markdown headers with code blocks for key-value pairs:

# Query Results

## Record 1

id: i-1234567890abcdef0
name: prod-web-01
region: us-east-1
instance_type: t3.large
state: running


## Record 2

id: i-0987654321fedcba0
name: staging-web-01
region: us-west-2
instance_type: t3.medium
state: stopped

The format combines clear hierarchy, explicit key-value pairs, and readability for both humans and LLMs.

Usage​

from pystackql import StackQL

stackql = StackQL()

# Query with Markdown-KV output
result = stackql.execute(
    """
    SELECT instanceId, instanceType, state, availabilityZone 
    FROM aws.ec2.instances 
    WHERE region = 'us-east-1'
    """,
    output='markdownkv'
)

# Use with LLMs
response = llm_client.complete(
    f"Identify instances that should be stopped:\n\n{result}"
)

Works in server mode too:

stackql = StackQL(server_mode=True)

result = stackql.execute(
    "SELECT name, region, encryption FROM google.storage.buckets WHERE project = 'my-project'",
    output='markdownkv'
)

When to Use It​

Markdown-KV is useful when:

• Feeding infrastructure data to LLMs for analysis, security reviews, or recommendations
• Building RAG pipelines that need to accurately retrieve and reason about infrastructure
• Accuracy matters more than token efficiency (infrastructure decisions typically do)
• Query results are focused datasets (most StackQL queries are)

The token cost is a real tradeoff, but infrastructure queries typically return targeted result sets, not massive datasets. When you're asking an LLM to analyze your production environment, accuracy matters.

Getting Started​

Update pystackql:

pip install --upgrade pystackql

Add output='markdownkv' to your execute calls or in the StackQL object instantiation:

result = stackql.execute(query, output='markdownkv')

Resources​

• ImprovingAgents.com research on LLM data formats
• pystackql v3.8.2 changelog
• pystackql documentation
• StackQL documentation

The Markdown-KV output format is available in pystackql v3.8.2 and later.

⭐ Star us on GitHub and join our community!