# Getting Started with Starter Edition

This guide walks through installing ADI Starter Edition in your coding agent, connecting and authenticating, and running your first governed query in the Beta.

> [!NOTE]
> **What the Beta covers.** The Beta runs at trust tier t1, which is generation-only. Your agent can discover capabilities, author and validate a contract, and generate contract-governed SQL with full provenance. At t1 the server does not execute SQL or read your warehouse, so you run the generated SQL in your own environment. Execution and warehouse access arrive with the t0 and t2 tiers (see the Starter Edition overview).

## Prerequisites

- A supported coding agent: Claude Code, Cursor, or Codex via a dedicated plugin, or OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification, via individual install
- A Zitadel account for authentication. You are prompted to sign in or create one when you connect; your account needs the analyst (query) role and an approved status before you can run queries
- The MCP endpoint, provided to you directly when you are accepted into the Closed Beta
- Optionally, a dataset of your own, plus a short description or data dictionary of it (see Step 4 for why). ADI also provides a synthetic dataset with a ready-made contract.

## Step 1: Install ADI

The quickest way to install Starter Edition is the **ADI plugin**, which bundles the ADI Skills and the MCP server configuration in a single install.

**Dedicated plugins** are available for Claude Code, Cursor, and Codex:

- **Claude Code:** `/plugin marketplace add agentic-data-intelligence/adi-starter`, then `/plugin install adi`
- **Codex:** `codex plugin marketplace add agentic-data-intelligence/adi-starter`, then `codex plugin add adi@adi`
- **Cursor:** `git clone https://github.com/agentic-data-intelligence/adi-starter.git`, symlink its `plugin/` folder to `~/.cursor/plugins/local/adi`, then reload Cursor

Once installed, you have the two ADI Skills (authoring and querying) and the ADI MCP server available in your agent, giving it the full workflow: discover capabilities, author and validate a contract, generate contract-governed SQL, and handle refusals.

**Compatible plugins and skills.** OpenClaw, Manus, and any other coding agents that support either the Open Plugins Specification or the Agent Skills Specification can use ADI this way, and it is also the route if you simply prefer installing the parts separately. Copy the two Skill folders (`adi-querying` and `adi-authoring`) into your agent's skills directory, then configure the ADI MCP server in your client by pointing it at the endpoint provided to you on acceptance. The MCP configuration is a small JSON block naming the server and its URL, for example:

```json
{
  "mcpServers": {
    "adi": {
      "type": "http",
      "url": "<the endpoint provided to you on acceptance>"
    }
  }
}
```

Where this file goes depends on your client (for a Claude Code or Cursor-style layout, `.mcp.json` in your project root); check your client's own MCP documentation for the exact location.

**Not yet invited?** Closed Beta access is invite-only. Installing the plugin or the Skills without an approved Zitadel role gets you as far as sign-in, but queries return a pending status until access is granted (see Step 2). If you would like to be invited, request early access at [agentic-data.com/access](https://agentic-data.com/access).

## Step 2: Connect and authenticate

However you installed, connecting to the ADI MCP server requires authentication. The server is reached over streamable HTTP; on first connection you sign in with, or create, a Zitadel account. There is no API key.

Zitadel is a Swiss-headquartered identity and authentication platform, and ADI uses it with data residency in Switzerland. You can find more information at [zitadel.com](https://zitadel.com) and in its [privacy policy](https://zitadel.com/docs/legal/policies/privacy-policy). During account creation you also accept Agentic Data Intelligence SA's [Terms of Service](https://agentic-data.com/terms) and [Privacy Policy](https://agentic-data.com/privacy), which govern Starter Edition use.

If your access is still being approved, the tools report a pending status until it is active.

## Step 3: Discover capabilities

Once connected, have your agent call `adi.get_capabilities`. This returns the active trust tier, the enabled feature set (including whether SQL execution is available), and the list of tools you can use. Expect trust tier `t1`, the four ADI tools (`adi.get_capabilities`, `adi.get_authoring_spec`, `adi.generate_query`, `adi.validate`), and your account showing the analyst role with an approved status. It is the equivalent of checking what the server will let you do before you start.

## Step 4: Choose your data and contract

ADI works with any dataset. A query is only ever generated against a contract, so you need one of the following.

**Use the provided synthetic dataset.** ADI ships a synthetic dataset as a DuckDB file that you can use to try the workflow end to end without connecting your own data. It comes with a ready-made contract, so you can go straight to asking questions. Even if you plan to author for your own data, it is worth asking your agent to show you this contract bundle first: its entities, metrics, and vocabulary documents are a concrete, working example to pattern your own contract against, rather than starting from the abstract structure alone.

**Author your own contract.** For your own data, have your agent call `adi.get_authoring_spec` to fetch ADI's canonical schema and authoring guidance, then author the contract bundle (the entities, metrics, dimensions, policies, and rules that describe your data). The authoring step draws on the domain context you provide, the definitions and which columns are sensitive, not just column names, so have a short description or data dictionary of your data to hand. At t1 the server does not read your warehouse, so you author from the spec and your own knowledge of the data rather than from server-side table introspection. Validate it with `adi.validate` before use. Validation catches real structural and semantic errors that a manual review misses, and returns path-pointed messages telling you what to fix. At t1 it checks the contract's structure and meaning, not the contract against your real tables, so a clean result confirms the contract is well-formed, not that it matches your warehouse exactly.

## Step 5: Ask a question

Ask in business language, not SQL. For example:

- "How many projects are there in total?"
- "What is the total budget by country?"
- "Show me the top 5 organisations by project count"

Guided by the Skill, your agent turns your question into a structured request and calls `adi.generate_query` against the contract. It receives contract-governed SQL plus provenance: which metric was used, how tables were joined, and what filters and time window were applied.

Generation is deterministic. The same structured request returns byte-identical SQL every time, so within a given contract the same question yields the same answer.

## Step 6: Run the query

You run the generated SQL yourself, in your own environment (your warehouse or a local engine); ADI does not execute it or see your data. Signature-gated execution, where only contract-compiled SQL runs through a verified path, is a capability of the execution tiers (t0 and t2).

## Tips for getting the most out of ADI

**Start with capabilities.** Call `adi.get_capabilities` at the start of a session so your agent knows the trust tier, the enabled tools, and whether execution is available.

**Permission is not the same as capability.** Your account may show you as approved with roles granted, but at t1 the server still has execution and warehouse access switched off. What your role permits and what the tier runs are two different things, so rely on `adi.get_capabilities` for what is actually available.

**Invest time in improving the contract.** ADI enables authoring a contract based on the information that you provide. The more context and the more that you review and improve the contract, the better the resulting analysis based on the contract will be. Since the contract is generated by your own agent it is by definition non-deterministic so the more you invest in refining the contract, the more value you will see.

**Validate every contract before you rely on it.** `adi.validate` catches errors that look fine on a manual read, including subtle ones that silently drop joins or rows. Treat a clean validation as the bar for a usable contract. At t1 this checks structure and meaning, not the contract against your real warehouse tables.

**Ask in business language.** ADI's value is in compiling your intent into governed SQL. Writing SQL by hand bypasses the contract and loses provenance.

**Read refusals carefully.** A refusal is not a dead end. It includes a reason, a code, and, where relevant, recovery information such as the metrics or group-bys that are allowed.

**Use relative time windows.** Requests like "last quarter" or "last 30 days" adapt to the current date automatically, which is more reliable than hardcoded ranges.

## Next steps

- Read the [Features page](https://docs.agentic-data.com/docs/starter-edition/features) for a detailed look at each MCP tool and the contract structure
- See the [Beta Notes and Known Issues page](https://docs.agentic-data.com/docs/starter-edition/beta-test) for current limitations and practical guidance
- Check the [Troubleshooting guide](https://docs.agentic-data.com/docs/reference/troubleshooting) if you run into issues