> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Agent Platform's MCP Server

Agent Platform exposes its features through a Model Context Protocol (MCP) server. Your AI assistant can connect to the platform and perform platform operations to let you build, evaluate, optimize, debug, and analyze agents.

A few common tasks include:

* Creating and editing projects, agents, and tools
* Running evaluations
* Inspecting live sessions and traces
* Diagnosing failures

You can perform all these operations from the platform UI as well. However, by using MCP server, you can perform these tasks from within your IDE, command-line, or terminal, without context-switching.

To use the MCP server, you install `@koreai/arch-mcp-tools` and configure your AI assistant.

## Prerequisites

* **Node.js 18 or later** — We recommend LTS version. The server starts using `npx` command.
* Access to [Agent Platform account](/agent-platform/getting-started#platform-access-and-allowlist-of-ips). [Authenticate](#authenticate) when you connect to it for the first time.
* MCP-compatible client.

## Install and Configure

The server (`@koreai/arch-mcp-tools`) is a standard stdio MCP server. The clients launch it using the command: `npx -y @koreai/arch-mcp-tools`. In your client's config, you add it as a server named: `arch-agent-platform`.

Provide the environment URL in one of the following ways:

* In the configuration file, add as value of `AGENTS_URL` parameter in the `env`.
* Pass `serverUrl` to `platform_connect`.
* On the first use, the tool asks you for the environment.

**Example: Add to Claude Code**

```bash theme={null}
claude mcp add arch-agent-platform -- npx -y @koreai/arch-mcp-tools
```

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

```json theme={null}
{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"],
      "env": {
        "AGENTS_URL": "https://example.com"
      }
    }
  }
}
```

**Example: Add to Cursor**

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

```json theme={null}
{
  "mcpServers": {
    "arch-agent-platform": {
      "command": "npx",
      "args": ["-y", "@koreai/arch-mcp-tools"],
      "env": {
        "AGENTS_URL": "https://example.com"
      }
    }
  }
}
```

**Example: Add to VS Code to Use GitHub Copilot**

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

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

**Example: Add to Codex CLI**

```bash theme={null}
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 theme={null}
[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` variable to pin an environment.

Alternatively, use a version of the following prompt in your AI coding tool's chat for it to do the configuration.

```text theme={null}
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.
```

{/* AG: How to verify the installation. That the MCP server loads and tools are available. */}

***

## Authenticate

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 `kore-platform-cli login`.
3. **Device authorization** — opens your browser and polls until approval completes in the same `platform_connect` call.

Credentials are stored securely and reused in future sessions.

***

## Use MCP Server

The server's name as available in the clients is `arch-agent-platform` and its tools are prefixed with `platform_` and `debug_`. These tools are grouped by functional area.

### Arch Build

Create and change platform projects, agents, tools, configuration, versions, deployments, and imports.

| Tool                     | Description                                              |
| :----------------------- | :------------------------------------------------------- |
| `platform_projects`      | Manage projects (list, get, create, update, delete)      |
| `platform_agents`        | Manage agents (list, get, save\_dsl)                     |
| `platform_versions`      | Manage agent versions (list, create, get, promote, diff) |
| `platform_deployments`   | Manage deployments (list, create, get, retire, rollback) |
| `platform_tools`         | Manage tools (list, get, create, update, delete, test)   |
| `platform_import_export` | Import and export projects                               |
| `platform_config`        | Manage project and LLM configuration                     |
| `platform_workspaces`    | List, switch, and inspect active workspaces              |

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

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

{/* AG: More queries.

- Do we want to describe how the requests are processed.
- Add some troubleshooting guidance.
- With any programmatic access comes the security considerations. See above for auth. Also consider, any api keys, permissions, and network requirements.

*/}