Using the MCP Server

ArtlessDev exposes Scenarios to AI agents through an MCP (Model Context Protocol) server, so an agent can read a Scenario’s boundary signature and record a verification result directly, in-session — without a human manually copying context back and forth.

What an agent can do

What any given agent can do is decided by the scopes on the API key it connects with (below). Across all of them:

• Read — a Scenario’s path, evidence, and both status axes; a Feature’s Scenarios; the surrounding boundary before making a change; and a Scenario’s verification pass history.
• Write — propose a new Scenario, refine an existing one, move its lifecycle status, delete a draft or restore one.
• Verify — open a verification pass, record findings against individual path steps, and close the pass with a fit or gap outcome.

A proposed Scenario writes a real, immediately queryable row — there is no separate staging object — and always lands in Draft lifecycle status with verification not attempted, regardless of what the connected agent claims about its own confidence. Draft is a publication state, not a verification outcome: a human publishes it when ready, entirely separately from whether anyone has checked it against reality.

Connecting with an API key

An API key is the credential for everything outside the app. It is a machine identity, never a stand-in for a user, and it never inherits anyone’s Project roles.

A key is scoped to exactly one Project. The Project comes from the key itself, exactly as the Workspace does, so the endpoint takes no workspaceId and no projectId parameter at all. An agent that needs to span two Projects holds one key per Project.

1. A Workspace admin opens API keys from account (avatar → Workspace → API keys) and creates a key: a name, the Project it acts in, the scopes it carries, and an optional expiry. Only Workspace admins see this page.
2. Save the token shown — it starts with adk_live_, is displayed once, and can never be retrieved again, only revoked and replaced.
3. Add the endpoint and token to your MCP client’s config, sending the token as a bearer Authorization header:

{
  "mcpServers": {
    "artlessdev": {
      "url": "https://<your-project>.supabase.co/functions/v1/mcp-server",
      "headers": {
        "Authorization": "Bearer adk_live_<your-key>"
      }
    }
  }
}

The exact endpoint for your Workspace is shown on the MCP page (avatar → Workspace → MCP), alongside a scope guide and a link to manage keys. For creating, testing, rotating and revoking keys, see API Keys.

The four scopes

Scope	What it buys
scenarios:read	List, search and read Scenarios in this key’s Project, along with their verification history.
scenarios:write	Change any part of a Scenario — create one, edit its title, place, parent or drift note, replace its path and evidence, and move its lifecycle status, including retiring it.
scenarios:verify	Open a verification pass, attach evidence about the Scenario as a whole, and close it.
scenarios:steps	Record what was found at individual path steps, with evidence.

The verify/steps split is the one worth remembering: closing a pass is what moves a Scenario’s verification status, so scenarios:steps can record per-step findings but can never declare a fit, and scenarios:verify can rule on a pass but not rewrite the step findings underneath it. Opening and abandoning a pass take either.

There is deliberately no admin scope and no wildcard — a key can never mint, list or revoke another key. A key is also never shown the tools it would be refused on, so an agent doesn’t waste a turn discovering the boundary.

mcp_agent vs. automation vs. api

Every status change records a change_source, and the non-human ones are kept distinct on purpose:

• mcp_agent — one agent, acting once, in a session, over MCP.
• automation — an unattended, recurring integration (CI or a webhook), gated by a paid entitlement, since it runs without anyone watching.
• api — an API key acting on its own authority through the REST API.

Keeping these separate preserves a real trust distinction: a status change an agent made once, live, in front of a person, is not the same claim as one an unattended pipeline made on a schedule.

MCP server access is available to every Workspace, and opening verification passes is rate-limited per Workspace.

The legacy Workspace token

Before API keys, MCP authenticated with a single per-Workspace token passed alongside a ?workspaceId= parameter. That token still works and is still shown on the MCP page, marked as deprecated, but it carries all four scopes across the whole Workspace with no Project boundary at all, and it is being retired on 18 December 2026 — responses authenticated with it already carry Deprecation and Sunset headers.

Migrating is a one-line change: create an API key, swap the Authorization header, and drop the workspaceId parameter. The key names one Project and only the scopes that integration actually needs, and can be revoked on its own without disturbing anything else.

Provenance

A Workspace-level Provenance setting on the MCP page controls whether propose_scenario accepts a source citation on agent-authored steps — Disabled drops citations, Optional accepts them, and Required rejects a proposal that carries none.