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.