MCP server

Give an agent the same domain model the dashboard has — under a scoped key, with the same policy, credit, and audit rules, and no long operations hidden inside one opaque call.

What it is

The Ray9 MCP server exposes the product model to MCP-compatible agents and clients. It is a façade over the same public /v1 contract that the API and CLI use — not a separate implementation with its own idea of what a Flow is.

That matters more for agents than for people. An agent that can create a Flow, run it, and read the resulting records is only safe if it is subject to exactly the same authorization, policy evaluation, credit reservation, budget, and audit rules as a human clicking the same buttons. It is.

Authentication

The MCP server authenticates with an organization-scoped Ray9 API key — the same kind of key the public API uses.

Scope it. An agent that needs to read a dataset should be given a key that reads datasets, not one that can publish Flow versions and raise budgets. Keys are scoped by organization, resource, and action precisely so that "what could this agent do if it misunderstood the task?" has a small answer.

Everything an agent does through MCP is attributed and audited under that key, and it spends that organization's credits under that organization's budgets.

What an agent can do

The tools map onto the ordinary lifecycle, because there is only one lifecycle:

Discover — list the template catalog, list the Flows in the organization.
Build — create a Flow draft, validate it, publish a version.
Run — create a run against a version, with an idempotency key and optional budget or route constraints. Get a durable run ID back immediately.
Watch — check a run's status, inspect its attempts and structured failures, cancel it.
Read — page through the records in a dataset, read change events from a monitor, read usage.

An agent that can do those things can go from "I need the current prices on this page" to a validated, versioned, repeatable dataset — and can be asked afterwards to explain exactly where each number came from.

Long operations are not hidden

This is the design rule that most distinguishes the MCP server from a naive tool wrapper.

An MCP tool never hides a long-running operation inside one opaque call. Creating a run returns a durable run ID, immediately. The agent then checks status, inspects attempts, cancels, or continues.

The alternative — a single scrape_this tool that blocks for four minutes and returns either data or an exception — produces agents that time out, retry blindly, spend credits twice, and cannot tell you what happened. Durable resource IDs let an agent behave like an operator: start the work, look at how it is going, decide what to do next.

Confirmation semantics

Some actions require explicit confirmation rather than being executed because an agent inferred they were a good idea:

destructive actions — deleting records, deleting a dataset,
budget increases,
sensitive credential access,
and local-session use, when local execution ships.

An agent may propose these. It does not get to quietly perform them because it decided the task called for it.

The same guarantees

Everything else in these docs applies unchanged when the caller is an agent:

Policy is evaluated before credits are spent. An agent cannot spend its way past a denial.
Hard constraints — geography, authentication, headful, sticky sessions — are not silently relaxed to make a run succeed, no matter how much an agent would like it to.
Failures are classified, not flattened into an exception. An agent that receives auth_required knows not to retry, which is a thing agents are otherwise notably bad at.
Runs, records, and change events carry the same provenance. An agent's output is as traceable as a human's.

Ray9 does not build features whose purpose is bypassing logins, paywalls, or access controls — and an agent asking nicely does not change that. The auth_required failure category is a statement of fact, not an obstacle for a sufficiently clever prompt.