Elliot

Elliot

Turn any API or database into MCP tools for Claude Code, Cursor, OpenClaw, and Codex — with built-in observability.

Documentation · Quickstart · Concepts · The five principles

Elliot is an open-source platform for turning the products you already have — REST APIs, SQL databases, files — into tools that AI agents can use well. Not just connected, but fast, safe, and observable: minimal token usage, structured errors the agent can recover from, and a full trace of every agent session.

The target user is a product engineer who has a working API or database today and wants AI agents to interact with it natively — with minimum tokens, clean error recovery, and full observability.

AX is to agents what UX is to users and DX is to developers. Elliot's job is to make AX measurable.

Table of contents

• Why Elliot
• Features
• Quickstart
• See it in action
• How it works
• Connect your coding agent
• Project layout
• Documentation
• Roadmap
• Contributing
• Community and support
• License

Why Elliot

Connecting an API to an agent is easy. Making it work well is not. Agents fail when:

• Tool descriptions are vague — the agent picks the wrong tool.
• Results are too large — the context window fills up before the answer does.
• Errors are unstructured — the agent cannot recover or escalate.
• Nothing is observable — you do not find out it is broken until a user complains.

Elliot makes each of these visible and fixable. Every tool ships with a structured schema, a token estimate, an actionable error shape, and a session trace — every call, every agent, attributed to a client and model.

Features

• Agent-ready by design — every tool is linted against five concrete principles before it ships: verb-first descriptions, typed parameters, context-sized results.
• Safe by default — parameterised SQL, read-only database transactions, env-var secrets, no keys in connector files. Connector files are safe to commit.
• Every call observable — tokens, latency, arguments, and errors for every agent call, streamed to an audit log and visible in Studio.
• One command to run — start the whole stack with Docker. No Python, Node, or toolchain to install.
• Works with every agent — Claude Code, Cursor, OpenClaw, and Codex. Elliot auto-registers with each.
• Agents build connectors — discover, build, lint, eval, deploy. The platform itself is agentic: agents can build connectors through Elliot.

Quickstart

Just want to run Elliot? The only prerequisite is Docker — no Python, Node, uv, or pnpm:

curl -LsSf https://raw.githubusercontent.com/EliBarak12/Elliot/main/scripts/install.sh | sh

This pulls the pre-built images, generates a local .env, starts all three services, and opens Studio at http://localhost:8080. Stop it any time with docker compose -f docker-compose.run.yml down.

Want to develop Elliot? Build from source instead:

# Prerequisites: uv (Python 3.13) and pnpm (Node 22)
git clone https://github.com/EliBarak12/Elliot.git && cd Elliot
make setup
make dev          # boots plugin (:3000) + studio (:5173)
                  # and writes the MCP config for every detected coding agent
                  # the runtime (:3001) starts on demand when you deploy a connector

Then open Studio at http://localhost:5173, scaffold a connector, lint it, and your agent can use it in the same session.

See it in action

A walkthrough of Elliot Studio — the visual dashboard that observes, runs, and edits everything an agent builds.

The loop above cycles through every Studio page. For the full-quality screencast, watch the video walkthrough.

Studio in detail:

Tools — verb-first, typed contracts your agents call. Design, validate, and test each one.	Metrics — calls, error rate, latency, and token efficiency across every tool.
Agent Console — a live trace of every agent session: prompts, tool calls, tokens, errors.	Sources — REST APIs, PostgreSQL, MySQL, and files, discovered and managed in one place.

How it works

1. Connect your data sources
   REST APIs, PostgreSQL, MySQL, CSV / JSON files — all in one connector

2. Build tools (no SQL required)
   Define name, description, parameters, filters, and return fields
   Elliot generates safe, parameterised queries
   Or let an agent build the connector for you with the agentic builder

3. Lint for agent-readiness
   elliot lint my-domain.connector.json

4. Write and run eval cases
   elliot eval my-domain.eval.yaml — pass/fail plus a token estimate

5. Deploy and connect agents
   plugin (:3000) serves tools to any MCP client
   runtime (:3001) executes them against live data
   studio observes, runs, and edits everything

6. (Optional) Ship the connector as a plugin
   elliot export-plugin my-domain.connector.json
   produces an installable Codex + Claude Code plugin folder

On first connect, an agent automatically calls prompts/get name=getting_started — a single prompt that teaches it the five principles, the canonical workflow, and the reference resources available.

Connect your coding agent

make dev runs elliot connect, which detects every coding agent on your machine and writes its MCP config automatically. To wire a client by hand:

/plugin marketplace add EliBarak12/Elliot
/plugin install elliot@elliot

{ "mcpServers": { "elliot": {
  "url": "https://api.elliot-cloud.com/b/mcp"
}}}

codex plugin marketplace add EliBarak12/Elliot

openclaw plugins install elliot@elliot

Every install path wires the MCP URL only — Elliot's server still needs to be running, locally or at a hosted endpoint. Skills ship in the repo-root skills/ directory; Claude Code and Codex auto-discover them, and every other MCP client receives the same guidance as MCP prompts.

Add Elliot to Claude.ai and Claude Desktop

The table above covers the Claude Code plugin. To use Elliot from Claude.ai (web) or the Claude Desktop / mobile apps, add it as a remote Connector — Elliot's hosted endpoint speaks the MCP HTTP transport and runs the full OAuth 2.1 handshake, so there are no keys to paste:

1. In Claude, open Settings → Connectors.
2. Click Add custom connector.
3. Paste the Elliot MCP URL and confirm:

   https://api.elliot-cloud.com/b/mcp
   

4. Claude registers itself (RFC 7591 dynamic client registration), then sends you to the Elliot consent screen. Sign in, click Allow, and Claude returns connected.

Elliot's tools now appear in the connector picker for every chat. The access grant is listed under Connected agents in the Elliot dashboard and can be revoked there at any time. Because the connector authenticates each user individually (scope: per_user), every teammate authorises with their own identity — no shared secret.

Self-hosting Elliot? Point the connector at your own deployment's /b/mcp URL instead. The OAuth discovery documents are served from the same host, so the only requirement is that it's reachable over HTTPS.

To get Elliot listed in Anthropic's built-in Connectors directory (so users can add it without pasting a URL), see docs/claude-connector-directory.md.

Ship a connector as its own plugin

Once you've built a connector, package it as a standalone plugin that installs in Codex and Claude Code:

elliot export-plugin my-domain.connector.json

This scaffolds a my-domain-plugin/ folder with the Codex and Claude Code manifests, marketplaces, an .mcp.json that serves the connector over stdio (elliot-mcp --connector), and a skills/ directory. The MCP server is named after the connector slug, so its tools are mcp__<slug>__<tool-id>; the generated skills — a usage guide plus one per connector workflow — already reference that prefix. Install it with /plugin marketplace add <folder> (Claude Code) or codex plugin marketplace add <folder> (Codex).

Project layout

Elliot is a monorepo of four packages:

Connector files live in connectors/, starter templates ship with the plugin (browse them via the elliot://templates/ MCP resources), and every environment variable is documented in .env.example.

Documentation

Full documentation lives at elibarak12.github.io/Elliot.

• Quickstart — get a connector running in minutes
• Concepts — sources, tools, skills, connectors
• The five principles — the design rules every connector follows
• Connector spec — the full .connector.json schema
• Architecture — how the three services fit together
• Deployment — Docker images, env vars, hosting

Roadmap

Elliot's goal is to be usable by everyone, not just developers. Progress is tracked in dev/docs/USER_ONBOARDING.md.

Contributing

Contributions are welcome — code, connectors, docs, and bug reports alike.

• Browse good first issues to get started.
• New connectors are especially valuable — see the connector request template.
• Before opening a PR, run the mandatory checks below. All six must pass.

uv run ruff check .
uv run ruff format --check .
uv run mypy packages/core/src packages/mcp-plugin/src packages/connector-runtime/src
uv run pytest --tb=short
pnpm --filter @elliot/studio run typecheck
pnpm --filter @elliot/studio test --run

Community and support

Found a bug, have a feature request, or want to propose a connector? Open an issue on the issue tracker — we read every one.

License

Elliot is released under the MIT License.