# Arch MCP Tools

`@koreai/arch-mcp-tools` is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that connects your AI coding assistant to the **Kore.ai Agent Platform**. It gives the assistant a set of tools to **build, evaluate, optimize, debug, and analyze** agents on the platform — create and edit projects, agents, and tools; run evaluations; inspect live sessions and traces; and diagnose failures — directly from your editor or terminal.

It works with any MCP-compatible client (Claude Code, Cursor, VS Code, Codex CLI, and others). The server is exposed to clients under the name **`arch-agent-platform`**, and its tools are prefixed `platform_*` and `debug_*`.

## `1.8.0` release

`@koreai/arch-mcp-tools@1.8.0` adds agent-engineering guidance skills for Claude Code and Codex. It
is a SemVer minor: no MCP tool, action or input changed.

**Twelve new skills.** `arch-agent-guide` routes a developer's question to the right skill, and
eleven task skills cover session explanation, experience contracts, topology, context budgets,
latency and cost, voice design, evals, release checks, tools, workflows and knowledge search. Each
asks the assistant for a plain-language answer with tables, quoted evidence and a glossary.

**Installer.** `arch-mcp-guidance install|uninstall` now acts on every bundled skill (`--skill`
picks a subset; `list` prints them). Every skill is checked before anything is written or removed.
Re-running `install` upgrades an earlier version's unmodified skills in place, including an
existing `arch-platform` install from 1.7.0.

```bash
npx -y -p @koreai/arch-mcp-tools@1.8.0 arch-mcp-guidance install --client claude --scope project
```

## `1.7.0` release

`@koreai/arch-mcp-tools@1.7.0` is the Artemis 1.7.0 line release. It supersedes the unpublished
`1.6.1` candidate, so everything below lands on top of `1.6.0`. It is a SemVer minor: every change
to an existing tool is additive, and no tool, action, or required input was removed.

**Complete project authoring.** The default `current-v2` profile grows from 45 to 60 tools so a
coding agent can finish a whole project through typed MCP operations instead of whole-project
import. New tools: `platform_knowledge_bases`, `platform_ingestion_pipelines`,
`platform_prompt_library`, `platform_feedback_templates`, `platform_external_agents`,
`platform_behavior_profiles`, `platform_guardrails`, `platform_alerts`, `platform_omnichannel`,
`platform_memory`, `platform_inbox`, `platform_insights_generator`, `platform_pipelines`,
`platform_analytics`, and `debug_resume_session`. Resource edits use direct, allow-listed Studio
routes with project-scoped authorization; destructive or costly actions (delete, rebuild,
reindex, guardrail activation, synthetic Insights save) require explicit confirmation. The catalog
now describes 326 schema-derived operations across 27 features.

`platform_arch_auto_loop` adds read-only `list_proposals` (run-scoped) so operators can read each
repair proposal with the gate results that blocked or rejected it before apply.

**Contract alignment.** In the default `current-v2` profile, `debug_list_agents` pages its
results: it accepts `projectId`, `limit` (1–100, default 50), and `offset`, and reports `total`,
`is_truncated`, and `next_offset`. **Callers that expected every agent in one call should follow
`next_offset`.** Against an older Runtime without pagination the full list is still returned.
`debug_load_agent` now forwards the Runtime load options it previously dropped — `deploymentId`,
`environment`, `versionId`, `initialMessage`, `callerData`, and `interactionContext` — and
`platform_versions` keeps pagination and typed promotion responses. Failed HTTP calls expose one
sanitized structured error (status, safe code, fields/details, correlation IDs) instead of a bare
message. The `legacy-v1` profile keeps its frozen schemas for all of these tools.

`platform_agents` adds `create` and a guarded `edit_dsl` that requires the current source hash, plus
Studio-backed `set_prompt_ref`/`get_prompt_ref` for library prompts; `save_dsl` remains available.
`platform_workflows` adds version activation, execution inspection, step approval, human-task, and
trigger lifecycle actions. `platform_config` adds project model selection
(`get_model_options`, `get_model_selection`, `set_model_selection`) with revision and idempotency
guards. For the end-to-end order, read `debug_docs` topic `mcp/project-build-playbook`.

**Historical debugging.** `debug_traces`, `debug_get_current_state`, `debug_get_span_tree`,
`debug_get_errors`, `debug_explain_decision`, `debug_get_flow_graph`, and `debug_analyze_session`
accept `projectId` and `source` so they can read durable, persisted sessions instead of only the
live buffer; `debug_session_history` adds cursor paging and `turnId`/`requestId`/`traceId`/
`failureCode` filters. `platform_arch_sop` adds `list_sessions`, `get_journal`, `get_transcript`,
`get_audit_timeline`, and `review_clarification` for historical Arch session evidence. Voice trace
types now include `voice_dead_air`, `voice_filler_playback`, and `voice_playback_watchdog`.

**Session identity outlives its transport.** A session ID returned by `debug_load_agent` used to
stop working while Runtime was still serving the session, because releasing the bounded WebSocket
also destroyed the session identity; the debugger then answered `Session not found` for a live
session and the only recovery restarted the conversation from the entry agent.

Identity now outlives its transport, and the store carries its own bounds. A released transport is
reported as recoverable, with the close code Runtime sent, so a harness can tell "the socket went
away" from "this session never existed" without matching prose. `debug_resume_session` reattaches a
known session on a fresh connection and reports `sessionIdChanged` when Runtime rebuilds it under a
new ID, rather than hiding the change. A session this debugger only OBSERVES through
`debug_session` is refused, because reattaching it would take the conversation away from the client
that owns it.

Each `debug_send_message` now resolves against its own reply where the platform echoes the caller's
request id, and falls back to the previous behaviour against an older Runtime.

`debug_send_message` also treats a model-provider error that Runtime handled with a fallback reply
(`agent_error_handled` with `errorType: "llm_error"`) as a failed turn, returning `success: false`
with the diagnostic code and message in `turnFailures[]`; other handled errors are unchanged.

**Compatibility.** The `legacy-v1` discovery profile keeps all 45 historical tool names and actions,
adds `debug_resume_session`, and changes existing schemas only additively (new optional inputs, new
actions, nullable widening). Clients pinned to exact schema hashes should re-snapshot. Several new
families call Studio routes that ship with the Artemis 1.7.0 platform; against an older deployment
those actions return the platform's not-found or permission error rather than succeeding.

For reproducible installation:

```bash
npx -y @koreai/arch-mcp-tools@1.7.0
```

## `1.6.0` release

`@koreai/arch-mcp-tools@1.6.0` is the Artemis 1.6.0 line release. It supersedes the unpublished
`1.5.2` candidate, so everything below lands on top of `1.5.1`.

**Tool results now match what actually happened.** A failed HTTP call carries the upstream cause
(for example `STAGING_FAILED: two records share the same unique key`) in the top-level `error`
instead of only the status line, so a client no longer reports a precise platform diagnosis as a
generic failure.

`debug_send_message` reports the turn outcome rather than merely that a response frame arrived.
Every response carries `turnStatus` (`"answered"` or `"failed"`), and a turn the runtime failed
returns `success: false` with `turnFailures[]` and an explanatory `error` — previously such a turn
returned `success: true` alongside a fallback apology, so a caller could not tell a working project
from a broken one. **This is a behavior change for callers that assert on `success`:** a turn that
genuinely answers is unaffected, but a failed turn now reports failure.

`debug_analyze_session` detects a planned specialist that was never dispatched. Runtime names every
intended specialist in `multi_intent_plan_built`, but the analyzer previously read only
`multi_intent_queue_accepted` — so a second request the model planned that never reached queue
acceptance left no evidence to match, and the analyzer reported `issues: []` on a turn that visibly
dropped work. The new rule compares the plan against dispatch traces for the same turn and names the
specialists that never ran. Targets that did reach acceptance stay with the existing
accepted-but-not-dispatched rule, so one dropped task is never counted twice.

`debug_traces` paginates honestly. It accepts an `offset` alongside `limit`, clamps `limit` to
`1..1000` and normalizes non-positive or fractional values instead of silently returning the whole
buffer, and every response reports `total`, `offset`, `limit`, `is_truncated`, and the buffer
`retention` window — so a caller can tell a complete result from a partial one. `totalMatches` is
retained for backward compatibility and equals `total`. `debug_get_current_state` and the client
event buffer are bounded on the same basis.

**Project-import guidance is corrected for new applications.** New MCP-authored packages should
omit `project.json` unless they have a complete platform-exported v2 manifest; a behavior-profile
fragment is no longer presented as a complete manifest. Matching platform versions also validate
and safely normalize legacy sparse v2 manifests instead of failing late with a generic
`IMPORT_FAILED` response.

This release preserves all 45 public tool names, schemas, discovery hashes, and existing
operations. The import validation fix is platform-owned; upgrading only the MCP package improves
authoring guidance but does not replace the matching platform deployment.

For reproducible installation:

```bash
npx -y @koreai/arch-mcp-tools@1.6.0
```

## `1.5.1` release

`@koreai/arch-mcp-tools@1.5.1` is a backward-compatible workflow-fidelity hotfix for the `1.5.x`
line. It preserves parseable authored workflow function source byte-for-byte at the explicit
`nodes[*].config.code` protocol path outside deterministic credential-sensitive syntax.
Parser-backed checks conservatively govern literal values beneath credential-sensitive targets and
recognized header/authorization forms: writes are rejected and reads are redacted. This boundary
can intentionally redact non-secret metadata placed beneath credential-shaped identifiers such as
`token`, `cookie`, or `password`; structured credential fields remain protected as before. It also
carries the complete writable canvas
contract across MCP, Runtime, and persistence:
loop `parentId`, edge `targetHandle`, variable namespaces, and nullable input/output schemas.

Compatibility guarantees for this hotfix:

- the `legacy-v1` discovery profile preserves all 45 historical tools, action names, and schemas;
- the default `current-v2` profile exposes the target-aware eval contract and
  `platform_config:get_runtime_config` while retaining all 45 existing tool names;
- existing requests remain valid because every new workflow input field is optional;
- `readOnly` remains server-owned and is not added to create/update inputs;
- older platform deployments continue to accept the requests they accepted before, although full
  round-trip fidelity for the new canvas fields requires the matching Runtime deployment; and
- `platform_workflows(create_tool)` now points callers to the supported
  `platform_versions(action: "publish")` lifecycle rather than the retired create action.

For reproducible installation:

```bash
npx -y @koreai/arch-mcp-tools@1.5.1
```

### Discovery profiles

The packaged server defaults to `current-v2`. Embedders can select the historical contract with
`discoveryProfile: "legacy-v1"`, and the CLI accepts the equivalent
`--discovery-profile legacy-v1` option. The legacy profile is intended for clients that require the
pre-target eval schemas and the pre-ABLP-4433 four-action `platform_config` schema; new integrations
should use `current-v2`.

Execution targets are typed and supplied only through the target field on eval create/update
operations. Studio resolves and locks the target for the run, and subsequent get/status responses
remain authoritative for the resolved target snapshot. Do not place a second target inside the
free-form request body.

### Migrating consumers to current-v2

`current-v2` is additive for existing projects. Calls that omit `target` retain the previous Studio
resolution and Runtime execution path; no project migration or Runtime behavior change is required.
Clients should ignore response fields they do not understand and should read the structured
`arch://contract/v2/manifest` resource instead of inferring capabilities from descriptions or tool
counts. The manifest identifies the active profile, declares that target-less requests preserve the
Runtime contract, and provides per-tool contract hashes.

New clients should use this sequence:

1. Read `arch://contract/v2/manifest`.
2. For target-aware evals, call `platform_eval_sets` with `action: "targets"`.
3. Pass exactly one typed `target` to the applicable create/update operation.
4. Read the returned run `status` or `get` response and treat its locked target snapshot as
   authoritative.

Clients that require the pre-target schemas, the four-action `platform_config` contract, or perform
exact schema matching can launch the server with `--discovery-profile legacy-v1`. This fallback
changes the published MCP contract only; it does not migrate project data or alter Runtime
execution.

## `1.5.0` release

`@koreai/arch-mcp-tools@1.5.0` is a substantial feature release while remaining a SemVer minor
update within the `1.x` compatibility line.

The release adds:

- code-derived coverage for all 45 public tools and 199 schema-declared operations across 13 feature
  groups;
- operation-scoped confidence, safety, prerequisites, limitations, dependencies, and verification
  guidance;
- additive `arch://guidance/v1/*` resources plus planning and verification prompts;
- one schema-gated Codex/Claude skill installed only through the ownership-safe
  `arch-mcp-guidance` command; and
- clean-package, authorization/isolation, compatibility, failure-isolation, and four-metric coverage
  gates.

The knowledge protocol remains schema version `1`; the package version and knowledge schema version
are intentionally independent. Existing 45-tool discovery, tool names and schemas, initialization
instructions, project-builder payloads/order, and prior-Studio downgrade behavior remain unchanged.
New resources and prompts are appended, and guidance construction fails soft without disabling the
legacy MCP surface.

Consumers can pin the release explicitly:

```bash
npx -y @koreai/arch-mcp-tools@1.5.0
```

## Requirements

- **Node.js 18 or newer** — the server runs via `npx`, no separate install needed.
- A **Kore.ai Agent Platform account** — you authenticate on first connect (see [Authentication](#authentication)).

## Install

`@koreai/arch-mcp-tools` is a standard **stdio MCP server**. Every client launches it the same way:

```
command:  npx
args:     -y  @koreai/arch-mcp-tools
```

Add it under a server named `arch-agent-platform` using your client's config below. The unpinned
form follows the npm `latest` tag; use `@koreai/arch-mcp-tools@1.8.0` for a reproducible install.
(No environment is baked in — see [Choosing an environment](#choosing-an-environment).)

### Claude Code

```bash
claude mcp add arch-agent-platform -- npx -y @koreai/arch-mcp-tools
```

Or add it to `.mcp.json` (project) or `~/.claude.json` (global):

```json
{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}
```

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` — note the top-level key is `servers` (not `mcpServers`):

```json
{
  "servers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"]
    }
  }
}
```

### Codex CLI

```bash
codex mcp add arch-agent-platform -- npx -y @koreai/arch-mcp-tools
```

Or add to `~/.codex/config.toml` — note this is **TOML**, not JSON:

```toml
[mcp_servers.arch-agent-platform]
command = "npx"
args = ["-y", "@koreai/arch-mcp-tools"]
```

### Any other MCP client

Configure a **stdio** server with command `npx` and args `["-y", "@koreai/arch-mcp-tools"]`. Optionally set an `AGENTS_URL` environment variable to pin an environment.

### Optional Codex or Claude guidance skills

The package ships a set of skills for Claude Code and Codex. Installation is explicit and never runs
as part of normal MCP startup.

| Skill                      | Use it for                                                                        |
| -------------------------- | --------------------------------------------------------------------------------- |
| `arch-agent-guide`         | Start here: routes a question to the right skill and sets the working rules       |
| `arch-platform`            | Planning and verifying platform operations from the code-backed operation catalog |
| `arch-explain-session`     | Turn-by-turn explanation of a session, the first wrong event and the fix          |
| `arch-experience-contract` | Per-intent success definitions, latency targets and model-call budgets            |
| `arch-topology`            | Single agent, flow or multi-agent topology, handoff context and multi-intent      |
| `arch-context-budget`      | What the model sees each turn, truncation markers and context growth              |
| `arch-latency-cost`        | Most expensive turns, model calls per turn and the lever for each                 |
| `arch-voice-design`        | ASR, listening settings, latency profile and realtime speech-to-speech            |
| `arch-eval-catalog`        | Scenario catalogs, evaluators and eval run comparison                             |
| `arch-tool-design`         | Tool contracts: effects, confirmation, idempotency, result shaping, errors        |
| `arch-workflow-design`     | Workflow-backed tools, sync vs async, versions, executions and human steps        |
| `arch-knowledge-search`    | Knowledge-base ingestion, retrieval settings, permissions and wrong answers       |
| `arch-release-check`       | Lint, validation, eval compare and the pre-ship checklist                         |

Every task skill asks the assistant for a plain-language answer with tables, quoted evidence and a
glossary, so the result can be checked rather than taken on trust.

```bash
# User scope
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client codex --scope user
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client claude --scope user

# Project scope (run in the project root)
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client codex --scope project
npx -y -p @koreai/arch-mcp-tools arch-mcp-guidance install --client claude --scope project
```

`install` and `uninstall` act on every bundled skill; add `--skill <name>` (repeatable) to pick a
subset, and run `arch-mcp-guidance list` to print the bundled skill names. The installer records
hashes in an ownership manifest per skill and checks every skill before writing or removing
anything, so a refused install or uninstall leaves all files unchanged. It refuses unmanaged or
modified files; a default `uninstall` skips same-named directories it does not own and reports them.
After a package upgrade, re-run `install`: it replaces skills installed by an earlier version in
place when their files are unchanged and the skill directory holds nothing else, and refuses
otherwise. From this release on, installing with an older package replaces newer skills the same way; to go
back to 1.7.0 or earlier, run this release's `uninstall` first. Operating-system
metadata files such as `.DS_Store` are ignored. `uninstall` removes only unchanged files owned by
this package and finishes an interrupted uninstall when re-run.

### Or just ask your assistant

Paste this into your coding tool's chat and it will wire the server up for you:

> Add an MCP server named `arch-agent-platform` that runs `npx -y @koreai/arch-mcp-tools`, and put it in this project's MCP config.
> Config location by tool — Claude Code: `.mcp.json` (`mcpServers`) · Cursor: `.cursor/mcp.json` (`mcpServers`) · VS Code: `.vscode/mcp.json` (`servers`) · Codex: `~/.codex/config.toml` (`[mcp_servers.arch-agent-platform]`).
> Optionally set `AGENTS_URL` to my environment.

## Choosing an environment

No environment is hardcoded. On first use, the tools ask which environment to connect to — or you can pin one by setting `AGENTS_URL` in the server's `env` (or by passing `serverUrl` to `platform_connect`).

| Environment | URL                              |
| ----------- | -------------------------------- |
| Production  | `https://agents.kore.ai`         |
| Dev         | `https://agents-dev.kore.ai`     |
| Staging     | `https://agents-staging.kore.ai` |
| QA          | `https://agents-qa.kore.ai`      |

Example with a pinned environment (Claude Code / Cursor shape):

```json
{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"],
      "env": {
        "AGENTS_URL": "https://agents.kore.ai"
      }
    }
  }
}
```

## Code-backed operation and dependency knowledge

Arch exposes additive `arch://guidance/v1/*` resources for the catalog manifest, feature families,
all schema-derived operations, dependency edges, and per-feature/per-tool detail. Every published
tool appears exactly once; actions come from the same effective input schema advertised to MCP
clients. Curated safety, scope, prerequisites, support, limitations, and verification references
are accepted only when they resolve to real tools/actions.

Use `plan-platform-operation` before multi-feature work and `verify-platform-operation` after a
specific action. Static dependencies guide ordering; authenticated project-builder reports remain
the authority for live project readiness. Features without public Arch MCP operations are not
presented as executable support.

For a full project, read `debug_docs` topic `mcp/project-build-playbook` (offline fallback) or
the connected Studio topic `guides/arch-mcp-project-build`. They order project, credentials,
integrations, data/tools/workflows, prompts/templates/external agents, guarded agent edits,
policy/channels/alerts, version publishing, deployment, evaluation, and live verification.
The sequence applies to any MCP client; MCP resources and prompts add structured detail when
the client exposes them.

## Tools

### Arch Build

Create and change platform projects, workflows, agents, tools, auth profiles, integrations, MCP servers, configuration, versions, deployments, and imports.

| Tool                                  | Description                                                                                                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform_projects`                   | Manage projects (list, get, create, update, delete)                                                                                                                                               |
| `platform_workflows`                  | Create, update, publish, execute, and expose workflows as tools                                                                                                                                   |
| `platform_auth_profiles`              | Manage profile metadata and start secure OAuth flows                                                                                                                                              |
| `platform_integrations`               | Create, update, test, and remove connector connections                                                                                                                                            |
| `platform_mcp_servers`                | Provision MCP servers; discover, import, and test tools                                                                                                                                           |
| `platform_agents`                     | List, get and create agents directly; guarded `edit_dsl` uses a source hash; Studio-backed `set_prompt_ref`/`get_prompt_ref` pin and verify library prompts. Legacy `save_dsl` remains available. |
| `platform_feedback_templates`         | List, get, create, update, inspect references and delete project feedback templates                                                                                                               |
| `platform_prompt_library`             | Author project prompts and versions, test, promote, inspect references and manage lifecycle                                                                                                       |
| `platform_external_agents`            | Register external agents, maintain endpoint/auth-profile metadata, and test connectivity                                                                                                          |
| `platform_alerts`                     | Discover metrics; create, update, test, and inspect project alert rules and evaluation history                                                                                                    |
| `platform_omnichannel`                | Manage project channel policy and signed mobile webhook integrations, health, tests, and rotation                                                                                                 |
| `platform_knowledge_bases`            | Manage KBs, inline text and linked index sources; inspect document/KB health and rebuild. Web source creation does not start crawling.                                                            |
| `platform_memory`                     | Read project persistent-memory declarations from agent DSL                                                                                                                                        |
| `platform_inbox`                      | Inspect and operate authorized project human tasks                                                                                                                                                |
| `platform_behavior_profiles`          | Author and inspect project Behaviour Profiles and their agent usage                                                                                                                               |
| `platform_guardrails`                 | Manage project policies and selected workspace providers; rules need names and executable checks, and enforcement needs a runtime trace.                                                          |
| `platform_insights_generator`         | Preview and explicitly save synthetic Insights data on entitled projects                                                                                                                          |
| `platform_pipelines`                  | Author and operate durable project pipelines, runs, and custom output rows                                                                                                                        |
| `platform_ingestion_pipelines`        | Draft, validate, publish, and reindex SearchAI ingestion flows for a project Knowledge Base                                                                                                       |
| `platform_versions`                   | Manage immutable versions (list, get, publish, qualifications, audit, diff)                                                                                                                       |
| `platform_deployments`                | Manage typed deployments (list, get, create, promote, rollback, restore, retire)                                                                                                                  |
| `platform_sdk_channels`               | Create SDK keys and web/mobile/API channels                                                                                                                                                       |
| `platform_tools`                      | Manage tools (list, get, create, update, delete, test)                                                                                                                                            |
| `platform_import_export`              | Import and export projects                                                                                                                                                                        |
| `platform_config`                     | Manage project, project-effective Runtime, and LLM configuration                                                                                                                                  |
| `platform_workspaces`                 | List, switch, and inspect active workspaces                                                                                                                                                       |
| `platform_arch_sop`                   | Drive Studio Arch SOP-build sessions                                                                                                                                                              |
| `platform_arch_auto_loop`             | Drive project-scoped Arch Auto Loop repair workflows                                                                                                                                              |
| `platform_project_builder`            | Discover provider contracts, inspect live dependencies/readiness, and plan                                                                                                                        |
| `platform_project_builder_operations` | Continue durable operations and execute attempt-bound governed actions                                                                                                                            |
| `agent_tables`                        | Manage Agent Tables definitions and project-scoped rows                                                                                                                                           |

For feedback, create a template in the same project, then put `FEEDBACK_TEMPLATE: <exact name>` inside the agent's `RICH_CONTENT: FEEDBACK` block. A template alone does not display a survey. Read template `references` before renaming or deleting; the server's guard covers authored working copies, not all published versions. Create an agent with `platform_agents:create`, read its `sourceHash`, then use `platform_agents:edit_dsl` with `expectedSourceHash` (`null` for a new draft). This goes through Studio's per-agent edit gate and returns 409 on a stale hash. Existing `save_dsl` writes through Runtime without that per-agent ACL or hash guard and is retained for compatibility. Project import is for a whole project package, not agent creation or edits.

For a library-backed system prompt, use `platform_prompt_library:create` and a draft version, optionally `test` with a configured tenant model, then `promote_version`. Create the agent directly with parseable DSL, call `platform_agents:set_prompt_ref` with the prompt/version IDs, and verify the server-resolved pin with `platform_agents:get_prompt_ref`. A draft or active version can be pinned; an archived version cannot. The prompt takes effect in a newly built agent version, not in an existing deployment. Read `references` before archive/delete; promotion and archival can conflict with draft-agent or runtime-filler references. Prompt tests can incur model cost and do not prove deployed behavior. The older Runtime-backed `platform_agents:get` does not expose the pin. On an ambiguous write error, read prompt/version or agent state before retrying. Project import is for whole packages, not these resource edits.

For external agent handoff, create the registry entry directly with `platform_external_agents`; use an AuthProfile ID when authentication is needed. Creation starts asynchronous discovery, so read the entry and test connectivity before wiring and exercising a live agent transfer. For alerts, discover catalog metrics first, then create a typed email or webhook rule; `test` evaluates without sending a notification. For omnichannel, read settings before patching, configure signed mobile webhook entries with an AuthProfile reference and version guard, then check health and run a separate live client test. SDK keys, deployments, provider channels, and live session joins are distinct steps. These edits do not use project import.

From a source checkout, build this package and run the opt-in local real-service smoke with `pnpm test:e2e:feedback-templates`, `ARCH_FEEDBACK_E2E_STUDIO_URL`, `ARCH_FEEDBACK_E2E_RUNTIME_URL`, and a Studio user `ARCH_FEEDBACK_E2E_ACCESS_TOKEN`. It accepts local loopback URLs only, creates its own project and verifies that the project becomes unreadable after the platform archives it for the deletion grace period. It covers the single-actor template/agent journey; cross-actor authorization and published rendering require the separate test-spec scenarios.

For the full project-surface smoke, start local Studio, Runtime, and SearchAI, then run `pnpm test:e2e:complete-surfaces` from this package with `ARCH_MCP_INSTALLED_BIN` set to the packed-and-installed package binary and `ARCH_MCP_LOGIN_FILE` set to a local dev-login JSON response containing `accessToken`. The runner creates and archives two run-owned projects, uses installed stdio MCP, checks that KB and source IDs from one project are rejected for the other, asserts independent readback for KB/profile/prompt/template, exercises a linked KB source and alert rule, and checks that a deployment manifest contains the exact published agent version. Insights dry run/save runs only if the tenant is entitled; a 403 is reported as an unverified gate. Review its JSONL output rather than treating the process exit code alone as full feature coverage.

#### Scalable project-builder protocol

The project-builder surface is intentionally feature-neutral. Clients learn the core ontology and
registered providers through `platform_project_builder(action: "describe")`, MCP resources, and
prompts. They do not reconstruct cross-feature dependencies by calling primitive tools and joining
responses locally.

Workflow is the first v1.1 provider. A future feature adds one provider registration with its own
qualified kinds, actions, schemas, imports/exports, readiness owner, and allow-listed Studio route
adapter; it does not add another top-level orchestration convention. Live requests negotiate Studio
contract support every time and then make one authoritative project/provider request. An absent or
ambiguous capability response is reported as `STUDIO_CAPABILITY_UNKNOWN`; only an explicitly lower
advertised contract is `STUDIO_UPGRADE_REQUIRED`.

Use `platform_project_builder_operations` for durable
list/read/report/resume/cancel/grant/execute flows.
Side effects require the exact operation version and attempt-bound grant returned by Studio. Never
retry a consumed attempt with an unknown outcome, and never send raw secrets—create or authorize an
auth profile through the secure Studio flow and pass only opaque references.

`platform_auth_profiles(create)` creates only `authType: "none"` profiles. Credential-bearing
profiles intentionally return a `secureSetupRequired` handoff because API keys, client secrets,
certificates, and tokens must never enter MCP/model context. After secure Studio setup, MCP can
list, inspect, update metadata, validate, revoke, initiate OAuth (including non-secret
`connectionConfig` template values), and bind the opaque profile ID to integrations or MCP servers.

### Arch Evaluate

Generate eval assets, run eval workflows, and read CI evidence.

| Tool                       | Description                                      |
| -------------------------- | ------------------------------------------------ |
| `platform_eval_personas`   | Manage and generate eval personas                |
| `platform_eval_scenarios`  | Manage and generate eval scenarios               |
| `platform_eval_evaluators` | Manage eval evaluators and templates             |
| `platform_eval_sets`       | Manage eval sets and discover execution targets  |
| `platform_eval_runs`       | Manage eval runs, preflight, cases, and heatmaps |
| `debug_harness_logs`       | Get CI execution logs                            |

### Arch Optimize

Validate packages, inspect compiler-visible models, and drive repair loops.

| Tool                          | Description                                                             |
| ----------------------------- | ----------------------------------------------------------------------- |
| `platform_validate_package`   | Validate a local package and optional import preview                    |
| `platform_package_model`      | Show compiler-visible agents, tools, constraints, refs, and diagnostics |
| `debug_lint_abl`              | Run ABL repair and design lint checks                                   |
| `debug_why_transcript_failed` | Correlate transcript symptoms with ABL file/line causes                 |
| `debug_diagnose_transcript`   | Alias for transcript failure diagnosis                                  |

### Arch Debug

Connect to live sessions, trace failures, and inspect execution state.

| Tool                         | Description                                          |
| ---------------------------- | ---------------------------------------------------- |
| `platform_connect`           | Connect and authenticate to the platform             |
| `debug_list_agents`          | List available agents by domain                      |
| `debug_load_agent`           | Load an agent and create a debug session             |
| `debug_send_message`         | Send a message to an agent                           |
| `debug_get_current_state`    | Inspect agent context, gather progress, flow state   |
| `debug_traces`               | Search trace events (type, text, agent, error)       |
| `debug_session_history`      | Page durable Runtime sessions and persisted traces   |
| `debug_resume_session`       | Reattach a known debug session on a fresh connection |
| `debug_get_span_tree`        | View hierarchical execution flow                     |
| `debug_explain_decision`     | Explain agent decisions with context                 |
| `debug_get_flow_graph`       | View state machine graph (JSON or Mermaid)           |
| `debug_get_errors`           | Get errors, warnings, and escalations                |
| `debug_list_active_sessions` | List observable sessions                             |
| `debug_session`              | Subscribe/unsubscribe to session traces              |

#### Loaded session identity

Each successful `debug_load_agent` result owns an independent Runtime connection. Loading another
agent does not invalidate earlier returned session IDs: pass the intended `sessionId` to
`debug_send_message` or `debug_get_current_state`, or omit it to use the most recently loaded
session. MCP retains at most 32 loaded-session connections, expires inactive entries after 30
minutes, and evicts the least recently used entry only after a replacement load succeeds
at that bound. Reconnecting with a new token, changing environments or workspaces, and stopping the
server close all retained loaded-session connections.

#### Historical session analysis

`debug_session_history` is the explicit, read-only alternative when a retained session must be
analyzed after its live MCP buffer is unavailable. It works the same from Codex, Claude, and any
standards-compatible MCP client. Connect to the intended Runtime with `platform_connect` first so
the existing bearer identity, workspace, and environment remain authoritative.

List a first page (defaults are `limit: 50`, `offset: 0`, `sortBy: lastActivityAt`,
`sortDir: desc`):

```json
{ "action": "list", "projectId": "project-id", "status": ["completed"], "range": "7d" }
```

Read a middle or final trace page by advancing `offset`; a beyond-final page is an empty successful
page, not an error:

```json
{
  "action": "get",
  "projectId": "project-id",
  "sessionId": "session-id",
  "limit": 200,
  "offset": 200,
  "types": ["llm_call", "tool_call"]
}
```

Runtime controls retention, authorization, ordering, and the returned `_meta.source`,
`source_chain`, `is_truncated`, `warnings`, and `errors`. The tool makes one bounded request (2 MiB,
10 seconds), never probes another route, retries, silently converts a concealed 404 to an empty
page, hydrates live stores, or falls back from historical data to the MCP live buffer. Errors are
returned as bounded MCP errors; do not place credentials or secrets in filter values.

The same explicit `source: "historical"` mode is available on `debug_analyze_session`,
`debug_traces`, `debug_get_current_state`, `debug_get_span_tree`, `debug_get_errors`,
`debug_explain_decision`, and `debug_get_flow_graph`. Historical trace search accepts
`failureCode`, `turnId`, `requestId`, and `traceId`; these are durable Runtime correlations, not
best-effort searches of the local live buffer. Use `stable: true` on history listing when a
repeatable snapshot is required, and return the Runtime-provided `nextCursor` unchanged on the
next request. `debug_list_active_sessions` and `debug_session` remain live-only subscription
surfaces. Historical results identify their source and completeness so degraded ClickHouse reads,
redaction, expiration, and retention boundaries are visible to the caller.

### Arch Analyze

Explain documentation, diagnostics, and system health signals.

| Tool                    | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `debug_docs`            | Get or search ABL documentation                                 |
| `debug_diagnose`        | Diagnose agent config and execution issues                      |
| `debug_analyze_session` | Automated session diagnostics                                   |
| `platform_analytics`    | Read project analytics, Insights, and built-in pipeline reports |

## Authentication

Authentication is automatic when you call `platform_connect` — it tries, in order:

1. **Explicit token** — pass an `authToken` parameter.
2. **Stored credentials** — reads the same encrypted credential store used by `artemis-platform-cli login`.
3. **Device authorization** — opens your browser and polls until approval completes in the same `platform_connect` call.

Credentials are saved for reuse in future sessions.

## License

MIT — see [LICENSE](LICENSE).