Wren Http Api

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.

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:

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

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:

{
  "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:

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.

Example: query

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

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:

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.

Response Format & Error Handling

SSE Response Format

The MCP server uses Server-Sent Events (SSE) for streaming responses. Each HTTP response contains one or more SSE events:

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

Parsing responses

1. Look for lines starting with data: 2. Parse the JSON after the data: prefix 3. Extract result.content[0].text for the tool output 4. Optionally use result.structuredContent.result for pre-parsed structured data

Shell one-liner:

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

Python example:

import httpx

resp = httpx.post(url, headers=headers, json=payload)
for line in resp.text.splitlines():
    if line.startswith("data: "):
        data = json.loads(line[6:])
        text = data["result"]["content"][0]["text"]

---

Error Handling

JSON-RPC protocol errors

If the JSON-RPC request itself is malformed, the response contains an error object instead of result:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params: ..."
  }
}

Common error codes:

Tool-level errors

Tools may return errors as text content with HTTP 200. Check the isError field or look for the ERROR: prefix:

{
  "result": {
    "content": [{ "type": "text", "text": "ERROR: File not found: /bad/path.json" }],
    "isError": true
  }
}

Read-only mode errors

Tools blocked by read-only mode (deploy, deploy_manifest, list_remote_tables, list_remote_constraints) return:

{
  "result": {
    "content": [{ "type": "text", "text": "ERROR: 'deploy' is disabled because read-only mode is active. Toggle it off in the Wren Engine Web UI." }],
    "isError": true
  }
}

Missing or expired session

If the Mcp-Session-Id header is missing or the session has expired, you will get an HTTP 400 response. Re-initialize the session to recover.

Wren MCP Tool Reference — HTTP JSON-RPC

Complete reference for calling each Wren MCP tool via tools/call.

Every example below assumes:

• Base URL: http://localhost:9000/mcp
• Headers: Content-Type: application/json, Accept: application/json, text/event-stream, Mcp-Session-Id: <SESSION_ID>

---

Health & Status

health_check

Check if Wren Engine is healthy and all configuration is in place. Returns a status report with actionable guidance for any missing configuration.

{ "name": "health_check", "arguments": {} }

is_deployed

Check if an MDL manifest is currently deployed.

{ "name": "is_deployed", "arguments": {} }

get_version

Get the MCP server version string.

{ "name": "get_version", "arguments": {} }

---

Deployment

deploy

Deploy an MDL from a JSON file path (path inside the container).

{ "name": "deploy", "arguments": { "mdl_file_path": "/workspace/target/mdl.json" } }

deploy_manifest

Deploy an MDL manifest dict directly (no file needed).

{
  "name": "deploy_manifest",
  "arguments": {
    "mdl": {
      "catalog": "wren",
      "schema": "public",
      "dataSource": "POSTGRES",
      "models": [
        {
          "name": "orders",
          "tableReference": { "schema": "public", "table": "orders" },
          "columns": [
            { "name": "order_id", "type": "INTEGER" },
            { "name": "status", "type": "VARCHAR" }
          ],
          "primaryKey": "order_id"
        }
      ],
      "relationships": [],
      "views": []
    }
  }
}

mdl_validate_manifest

Validate an MDL manifest via ibis-server dry-plan without deploying.

{ "name": "mdl_validate_manifest", "arguments": { "mdl": { "catalog": "wren", "schema": "public", "dataSource": "POSTGRES", "models": [] } } }

---

Query Execution

query

Execute a SQL query against the deployed MDL. Returns {"columns":[...], "data":[...], "dtypes":{...}}.

{ "name": "query", "arguments": { "sql": "SELECT * FROM orders LIMIT 10" } }

dry_run

Validate a SQL query without executing it (cheap syntax + schema check).

{ "name": "dry_run", "arguments": { "sql": "SELECT * FROM orders LIMIT 10" } }

---

Metadata — MDL Introspection

These tools read from the currently deployed MDL manifest.

get_manifest

Get the full deployed MDL manifest as JSON.

{ "name": "get_manifest", "arguments": {} }

get_available_tables

List all table (model) names in the deployed MDL. Returns an array of strings.

{ "name": "get_available_tables", "arguments": {} }

get_table_info

Get info for a specific table including column names.

{ "name": "get_table_info", "arguments": { "table_name": "orders" } }

get_column_info

Get detailed info for a specific column (type, expression, relationship, etc.).

{ "name": "get_column_info", "arguments": { "table_name": "orders", "column_name": "order_id" } }

get_table_columns_info

Batch get column info for multiple tables at once. Efficient for large MDL manifests.

{
  "name": "get_table_columns_info",
  "arguments": {
    "table_columns": [
      { "table_name": "orders", "column_names": ["order_id", "status"] },
      { "table_name": "customers" }
    ],
    "full_column_info": true
  }
}

get_relationships

Get all relationships defined in the deployed MDL.

{ "name": "get_relationships", "arguments": {} }

get_current_data_source_type

Get the current data source type (e.g. postgres, bigquery, duckdb).

{ "name": "get_current_data_source_type", "arguments": {} }

get_available_functions

Get all SQL functions available for the connected data source.

{ "name": "get_available_functions", "arguments": {} }

get_wren_guide

Get usage tips for Wren Engine, tailored to the connected data source type.

{ "name": "get_wren_guide", "arguments": {} }

---

Remote Database Introspection

These tools query the live database (not the MDL). Blocked when read-only mode is active.

list_remote_tables

List all tables in the connected database with schema and column metadata.

{ "name": "list_remote_tables", "arguments": {} }

list_remote_constraints

List foreign key constraints in the connected database.

{ "name": "list_remote_constraints", "arguments": {} }