# 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.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 179 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.6.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 skill

The package ships one canonical `arch-platform` skill grounded in the server's versioned operation
catalog. Installation is explicit and never runs as part of normal MCP startup:

```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
```

The installer refuses unmanaged or modified files and records hashes in an ownership manifest.
Replace `install` with `uninstall` to remove only unchanged files owned by this package.

### 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.

## 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`                     | Manage agents (list, get, save_dsl)                                              |
| `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                          |

#### 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_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.

### 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              |

## 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).