Agent skill

wren-http-api

Interact with Wren Engine MCP server via plain HTTP JSON-RPC requests — no MCP client SDK required. Covers session initialization, tool discovery, and calling all 20+ Wren tools (query, deploy, metadata, health check) using standard HTTP POST with JSON-RPC 2.0 payloads. Use when the client cannot or prefers not to use the MCP protocol directly (e.g. OpenClaw, custom HTTP clients, shell scripts, or any environment without an MCP SDK).

View SKILL.md on GitHub Repository
Stars 639
Forks 183

Install this agent skill to your Project

npx add-skill https://github.com/Canner/wren-engine/tree/main/skills-archive/wren-http-api

Metadata

Additional technical details for this skill

author
wren-engine
version
1.0

SKILL.md

Interact with Wren MCP via HTTP JSON-RPC

Version check

Silently fetch https://raw.githubusercontent.com/Canner/wren-engine/main/skills/versions.json. Compare the wren-http-api key with this skill's version (from the frontmatter above). If the remote version is newer, notify the user before proceeding:

A newer version of the wren-http-api skill is available. Update with:

npx skills add Canner/wren-engine --skill wren-http-api --agent claude-code

Then continue with the workflow below regardless of update status.

Overview

The Wren MCP server exposes a streamable-http endpoint that speaks JSON-RPC 2.0 over plain HTTP POST. Any HTTP client (curl, httpx, fetch, requests) can call Wren tools without an MCP SDK.

Base URL: http://localhost:9000/mcp (default Docker setup from wren-mcp-setup)

All requests use:

  • Method: POST
  • Content-Type: application/json
  • Accept: application/json, text/event-stream

Step 1 — Initialize a session

Before calling any tool, initialize a JSON-RPC session. The server returns a Mcp-Session-Id header that must be included in all subsequent requests.

bash
curl -s -D - http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0" }
    }
  }'

Save the Mcp-Session-Id header from the response. Then complete the handshake:

bash
curl -s http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

The initialized notification has no id field — it is a JSON-RPC notification, not a request.

Or run the helper script: bash scripts/session.sh http://localhost:9000/mcp

Step 2 — Discover available tools

bash
curl -s http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

Returns result.tools — an array of tool definitions with name, description, and input schema.

Step 3 — Call tools

All tool calls use the tools/call method with this structure:

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { ... }
  }
}

Responses arrive as Server-Sent Events (SSE). Parse the data: line:

event: message
data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"..."}]}}

Extract the tool output from result.content[0].text. Shell shortcut:

bash
curl -s ... | grep '^data: ' | sed 's/^data: //' | jq '.result.content[0].text'

See references/response-format.md for full response parsing and error handling details.

Available Tools — Quick Reference

All arguments are passed inside params.arguments. See references/tools.md for full details, argument tables, and example payloads for every tool.

Category Tool Arguments Description
Health health_check — Check engine health and configuration
is_deployed — Check if MDL is deployed
get_version — Get MCP server version
Deploy deploy mdl_file_path Deploy MDL from a JSON file path
deploy_manifest mdl Deploy MDL dict directly
mdl_validate_manifest mdl Validate MDL without deploying
Query query sql Execute SQL query
dry_run sql Validate SQL without executing
Metadata get_manifest — Get full deployed MDL
get_available_tables — List model/table names
get_table_info table_name Get table info + column names
get_column_info table_name, column_name Get column detail
get_table_columns_info table_columns, full_column_info? Batch column lookup
get_relationships — Get all MDL relationships
get_current_data_source_type — Get data source type
get_available_functions — List SQL functions for data source
get_wren_guide — Get usage tips
Remote DB list_remote_tables — List tables in connected DB
list_remote_constraints — List foreign key constraints

Example: query

bash
curl -s http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "query",
      "arguments": { "sql": "SELECT * FROM orders LIMIT 5" }
    }
  }'

Example: deploy_manifest

bash
curl -s http://localhost:9000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 11,
    "method": "tools/call",
    "params": {
      "name": "deploy_manifest",
      "arguments": {
        "mdl": {
          "catalog": "wren",
          "schema": "public",
          "dataSource": "POSTGRES",
          "models": [],
          "relationships": [],
          "views": []
        }
      }
    }
  }'

Prerequisites

This skill assumes the Wren MCP server is already running with streamable-http transport. If not set up yet, use the wren-mcp-setup skill or run:

bash
docker run -d --name wren-mcp \
  -p 8000:8000 -p 9000:9000 -p 9001:9001 \
  -e ENABLE_MCP_SERVER=true \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 -e MCP_PORT=9000 \
  -e WREN_URL=localhost:8000 \
  -e MDL_PATH=/workspace/target/mdl.json \
  -v <WORKSPACE_PATH>:/workspace \
  ghcr.io/canner/wren-engine-ibis:latest

Configure connection info via the Web UI at http://localhost:9001.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

Canner/wren-engine

wren-usage

Wren Engine CLI workflow guide for AI agents. Answer data questions end-to-end using the wren CLI: gather schema context, recall past queries, write SQL through the MDL semantic layer, execute, and learn from confirmed results. Use when: user asks a data question, requests a report or analysis, asks about metrics, revenue, customers, orders, trends, or any business data; user says 'how many', 'show me', 'what is the', 'top N', 'compare', 'trend', 'growth', 'breakdown'; user wants to explore, analyze, filter, aggregate, or summarize data from a database; agent needs to query data, connect a data source, handle errors, or manage MDL changes via the wren CLI.

639 183
Explore
Canner/wren-engine

wren-generate-mdl

Generate a Wren MDL project by exploring a database with available tools (SQLAlchemy, database drivers, MCP connectors, or raw SQL). Guides agents through schema discovery, type normalization, and MDL YAML generation using the wren CLI. Use when: user wants to create or set up a new MDL, onboard a new data source, or scaffold a project from an existing database.

639 183
Explore
Canner/wren-engine

wren-dlt-connector

Connect SaaS data (HubSpot, Stripe, Salesforce, GitHub, Slack, etc.) to Wren Engine for SQL analysis. Guides the user through the full flow: install dlt, pick a SaaS source, set up credentials, run the data pipeline into DuckDB, then auto-generate a Wren semantic project from the loaded data. Use this skill whenever the user mentions: connecting SaaS data, importing data from an API, dlt pipelines, loading HubSpot/Stripe/Salesforce/GitHub/Slack data, querying SaaS data with SQL, or setting up a new data source from a REST API. Also trigger when the user already has a dlt-produced DuckDB file and wants to create a Wren project from it.

639 183
Explore
Canner/wren-engine

wren-usage

Wren Engine — semantic SQL engine for AI agents. Query 22+ data sources (PostgreSQL, BigQuery, Snowflake, MySQL, ClickHouse, etc.) through a modeling layer (MDL). This skill is the main entry point: it guides setup, delegates to focused sub-skills for SQL authoring, MDL generation, project management, and MCP server operations. Use when: write SQL, query data, generate or update MDL, change database connection, manage YAML projects, set up or operate MCP server, or get started with Wren Engine for the first time.

639 183
Explore
Canner/wren-engine

wren-mcp-setup

Set up Wren Engine MCP server via Docker and register it with an AI agent. Covers pulling the Docker image, running the container with docker run, mounting a workspace, configuring connection info via the Web UI (with Docker host hint), registering the MCP server in Claude Code (or other MCP clients) using streamable-http transport, and starting a new session to interact with Wren MCP. Trigger when a user wants to run Wren MCP in Docker, configure Claude Code MCP, or connect an AI client to a Dockerized Wren Engine.

639 183
Explore
Canner/wren-engine

wren-project

Save, load, and build Wren MDL manifests as YAML project directories for version control. Use when a user wants to persist an MDL as human-readable YAML files, load a YAML project back into MDL JSON, or compile a YAML project to a deployable mdl.json file.

639 183
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results