Articles in this section

AI Agent API

  • Updated
Follow

The Etlworks AI Agent API lets your applications and AI agents drive Etlworks programmatically — search the knowledge base, execute CLI commands, import templates, and have full conversations with Simba (the Etlworks AI agent) over a simple REST API.

Full reference and downloads on the marketing site: etlworks.com/dev/ai/ — quickstart, API reference, examples, and client scripts (cURL, Python, Bash, PowerShell).

What you can do

Capability What it gives you
Direct tool access Call individual agent tools — search knowledge base, run CLI commands, search and import templates — without going through the LLM.
Full agent chat Send messages and get intelligent responses. The agent automatically selects and chains tools to answer complex questions.
Real-time streaming Stream responses token by token via Server-Sent Events. See tool calls in progress and get usage metrics live.
Multi-turn sessions Persistent sessions that remember context across messages — for complex workflows that need state.
Subagent integration Use Etlworks as a subagent in LangChain, CrewAI, AutoGen, or any orchestration framework. Delegate data integration tasks to a specialist.
API key auth Bearer token in the Authorization header. No OAuth flows, no token refresh.

Quick example

One-shot chat — ask the agent anything:

curl -s https://app.etlworks.com/rest/v1/ai-agent/api/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "How do I create a REST API connection to load JSON data?"}'

Execute a tool directly without the LLM:

curl -s https://app.etlworks.com/rest/v1/ai-agent/api/tools/search_knowledge_base/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "schedule a flow to run every hour"}'

Python client — one-shot chat, direct tool execution, and multi-turn sessions:

from etlworks_agent import EtlworksAgent

agent = EtlworksAgent("https://app.etlworks.com", api_key="YOUR_API_KEY")

# One-shot chat
result = agent.chat("How do I create a REST API connection?")
print(result["response"])

# Execute a tool directly
kb = agent.execute_tool("search_knowledge_base", {"query": "schedule a flow"})
print(kb["result"])

# Multi-turn session
session = agent.create_session()
r1 = agent.session_chat(session, "Create a connection to api.example.com")
r2 = agent.session_chat(session, "Now schedule it to run every hour")

Full reference

Quickstart, complete API reference, downloadable client scripts (cURL, Python, Bash, PowerShell), and worked examples: etlworks.com/dev/ai/.

Etlworks as an MCP server

Etlworks also exposes the same agent tools through an MCP (Model Context Protocol) server. External AI clients — Claude Desktop, Claude Code, Cursor, Windsurf, and any other MCP-aware tool — can connect to your Etlworks instance and drive it through natural-language interactions.

Endpoint

POST https://<your-instance>.etlworks.com/rest/v1/ai-agent/mcp

Transport is MCP Streamable HTTP — JSON-RPC 2.0 over a single path. Requests are POST; a GET returns 405 with Allow: POST.

The endpoint is stateless. No Mcp-Session-Id is issued or required, so it works behind a load balancer with multiple replicas and needs no session affinity. Each request stands on its own, authenticated by its bearer token. (Conversation continuity for etlworks_assistant is carried by the session_id in the tool arguments, not by the transport.)

Protocol versions

The server supports 2025-06-18, 2025-11-25, and 2026-07-28, and it is dual-era: the same endpoint answers both the legacy initialize handshake and the stateless per-request form introduced by 2026-07-28. Existing clients are unaffected by the upgrade.

A request is treated as modern if and only if it carries params._meta["io.modelcontextprotocol/protocolVersion"]. Anything else follows the legacy path.

The 2026-07-28 stateless form

The 2026-07-28 revision removed initialize and notifications/initialized from the spec. There is no connection to set up and no negotiated state to carry, so each request declares its own protocol version and client capabilities in a reserved _meta object under params. server/discover replaces the handshake:

curl -s https://app.etlworks.com/rest/v1/ai-agent/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

What the server enforces and returns on the modern path:

Rule Detail
Required _meta keys io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities. A missing or non-object clientCapabilities returns 400 with -32021.
Mirrored headers Mcp-Method on every request, plus Mcp-Name on tools/call. Each must equal the matching value in the body; a missing or mismatched header returns 400 with -32020. Send MCP-Protocol-Version as well — it is validated when present.
Unsupported version 400 with -32022. The error body includes data.supported and data.requested so a client can see what to fall back to.
Every result Carries resultType: "complete" — this server always completes synchronously — and serverInfo under io.modelcontextprotocol/serverInfo.
Cache directives server/discover returns ttlMs: 60000 and cacheScope: "public". tools/list returns ttlMs: 60000 and cacheScope: "private", because the visible tool set depends on the caller's token.
Unknown method HTTP 404 with a -32601 body. Legacy clients still receive HTTP 200 with the same error code.

Alongside the standard JSON-RPC codes — -32700, -32600, -32601, -32602, -32603 — requests on 2026-07-28 can return the MCP-reserved codes -32020 (header mismatch), -32021 (missing client capability), and -32022 (unsupported protocol version).

Full protocol reference, client setup, and worked examples: etlworks.com/dev/ai/mcp.html.

Authentication

Pass your Etlworks API key as a bearer token:

Authorization: Bearer <your-api-key>

API keys are managed under Account → Security → API keys. The MCP server inherits the same tenant scoping as the REST AI Agent API — all calls run as the principal that owns the key.

Etlworks does not issue OAuth tokens and does not offer OAuth 2.1 discovery (RFC 9728 protected-resource metadata), so there is no authorization flow to complete. One-click web connectors that rely on OAuth auto-configuration cannot register themselves — configure the API key manually in the client, as shown below.

Tools exposed

The MCP server exposes the same agent tools that Simba uses internally. Highlights:

  • Knowledge base and templates — search_knowledge_base, search_templates, search_function_templates.
  • Metadata and resources — metadata_search_resources, metadata_search_resource_types, mapping_lookup_metadata, composer_search_block_types.
  • Build and mutate flows — standard_flow_create, standard_flow_create_from_template, composer_apply_flow_update, mapping_apply_operations, composer_save_run_flow, composer_manage_schedule.
  • Resources — metadata_create_resource, metadata_create_http_connection, import_template.
  • Host CLI — host_cli (gated; requires explicit enablement), host_list_commands.
  • Web and account — public_web_research, create_support_ticket, book_demo, start_free_trial.
  • etlworks_assistant — a synthetic tool that runs the full Simba agent loop with tool access. Useful when the client wants Etlworks to do the planning rather than orchestrate tools individually. Gated by configuration; consumes AI tokens against your account's allowance.

Only tools are exposed — see What's not implemented.

Configure an MCP client

For Claude Desktop, add to your claude_desktop_config.json:

{
  "mcpServers": {
    "etlworks": {
      "url": "https://<your-instance>.etlworks.com/rest/v1/ai-agent/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Other MCP clients (Claude Code, Cursor, Windsurf) follow the same pattern — the URL and the bearer token are the only two values that change.

What's not implemented

The Etlworks MCP server implements tools and tool-calling. The implemented JSON-RPC methods are server/discover, initialize, notifications/initialized, ping, tools/list, and tools/call.

Not built. These exist in the spec and are not implemented, so don't spend time looking for them: MCP resources, prompts, sampling, elicitation, subscriptions/listen, multi-round-trip input_required results, progress notifications, pagination cursors, and outputSchema / structuredContent. They may arrive later if there is demand — they are not broken, just not built yet.

Removed from the protocol. Three items are no longer part of MCP at all: sessions, the server-initiated GET SSE stream, and stream resumability. The 2026-07-28 revision removed them from the spec, and over HTTP a client now cancels by closing the response stream rather than by sending a notification. Their absence is the specified behavior, not a deferred feature — which is also why a GET to the endpoint correctly returns 405, and why a session header sent by an older client is ignored.

MCP vs. the REST AI Agent API

The two endpoints share the same tool registry and authentication. The difference is the transport:

  • REST AI Agent API — HTTPS with a single request / response per call. Best for backend integrations and scripts.
  • MCP server — JSON-RPC over HTTPS, designed to be plugged into IDE / desktop AI clients. Best for human-in-the-loop assistant workflows.

Pick the one that fits your client. The REST API remains the primary integration path; MCP is a convenience transport for AI-agent clients.

Related articles