Arch MCP Tools

@koreai/arch-mcp-tools is a Model Context Protocol (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.

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

Related MCP server: Qdrant Neo4j Crawl4AI MCP Server

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:

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:

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:

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:

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

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

Claude Code

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

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

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

Cursor

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

{
  "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):

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

Codex CLI

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

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

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

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.

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

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

{
  "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.

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.

Arch Optimize

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

Arch Debug

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

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):

{ "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:

{
  "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.

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.