Epic: Implement 21 unimplemented MCP tools

[jeremyeder]

Overview

PR #23 replaced the oc CLI-based architecture with HTTP-based gateway auth via httpx. PR #26 merged it. The runtime now has 8 implemented tools. The original design called for many more tools that were documented but never implemented.

This epic tracks all unimplemented tools for future work. API specs are preserved below from the pre-cleanup API_REFERENCE.md.

The 8 Implemented Tools (current)

acp_list_sessions, acp_get_session, acp_create_session,
acp_delete_session, acp_bulk_delete_sessions,
acp_list_clusters, acp_whoami, acp_switch_cluster

---

Unimplemented Tools by Category

Session Lifecycle (5 tools)

• acp_restart_session — Restart a stopped session
• acp_clone_session — Clone an existing session configuration
• acp_create_session_from_template — Create session from predefined template (triage/bugfix/feature/exploration)
• acp_update_session — Update session metadata (display name, timeout)
• acp_export_session — Export session config + transcript for archival (backend: ambient-code/platform PR #625 adds export chat to the frontend)

Observability (3 tools)

• acp_get_session_logs — Retrieve container logs for debugging
• acp_get_session_transcript — Retrieve conversation history (JSON or Markdown)
• acp_get_session_metrics — Get usage statistics (tokens, duration, tool calls)

Labels (5 tools)

• acp_label_resource — Add labels to sessions (format: acp.ambient-code.ai/label-{key}={value})
• acp_unlabel_resource — Remove labels from resources
• acp_bulk_label_resources — Label multiple resources (max 3, with confirmation)
• acp_bulk_unlabel_resources — Remove labels from multiple resources
• acp_list_sessions_by_label — List sessions matching label selectors

Bulk Operations (5 tools)

• acp_bulk_stop_sessions — Stop multiple running sessions
• acp_bulk_delete_sessions_by_label — Delete sessions matching label selector
• acp_bulk_stop_sessions_by_label — Stop sessions matching label selector
• acp_bulk_restart_sessions — Restart multiple stopped sessions (max 3)
• acp_bulk_restart_sessions_by_label — Restart sessions matching label selector

Cluster & Workflows (3 tools)

• acp_login — Web-based or token authentication flow
• acp_add_cluster — Add new cluster to configuration file
• acp_list_workflows — Discover available workflows from Git repository

---

Preserved API Specifications

acp_restart_session

Restart a stopped session.

Input Schema:

{
  "project": "string (required)",
  "session": "string (required)",
  "dry_run": "boolean (optional, default: false)"
}

Behavior:

• Get current session status
• If dry_run: Return current status and preview
• Patch session with {"spec": {"stopped": false}}
• Requires public-api gateway endpoint: PATCH /v1/sessions/{session}

---

acp_clone_session

Clone an existing session with its configuration.

Input Schema:

{
  "project": "string (required)",
  "source_session": "string (required)",
  "new_display_name": "string (required)",
  "dry_run": "boolean (optional, default: false)"
}

Behavior:

• Get source session spec via GET /v1/sessions/{source}
• Copy spec, update displayName, set stopped: false
• Create via POST /v1/sessions with modified spec

---

acp_create_session_from_template

Create session from predefined template.

Input Schema:

{
  "project": "string (required)",
  "template": "string (required) - triage|bugfix|feature|exploration",
  "display_name": "string (required)",
  "repos": "array[string] (optional)",
  "dry_run": "boolean (optional, default: false)"
}

Templates:

{
  "triage": {"workflow": "triage", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.7}},
  "bugfix": {"workflow": "bugfix", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.3}},
  "feature": {"workflow": "feature-development", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.5}},
  "exploration": {"workflow": "codebase-exploration", "llmConfig": {"model": "claude-sonnet-4", "temperature": 0.8}}
}

---

acp_update_session

Update session metadata (display name, timeout).

Input Schema:

{
  "project": "string (required)",
  "session": "string (required)",
  "display_name": "string (optional)",
  "timeout": "integer (optional) - seconds",
  "dry_run": "boolean (optional, default: false)"
}

Behavior:

• Get current session
• Build patch with changed fields
• Apply via PATCH /v1/sessions/{session}

---

acp_export_session

Export session configuration and transcript for archival.

Implementation note: The frontend is adding an "export chat" feature in ambient-code/platform PR #625. This MCP tool should consume that same backend endpoint once available, rather than reimplementing export logic.

Input Schema:

{
  "project": "string (required)",
  "session": "string (required)"
}

Behavior:

• Call the export endpoint added by platform PR #625
• Return session config, transcript, and metadata in a structured format
• Blocked on: ambient-code/platform PR #625 (frontend export chat)

---

acp_get_session_logs

Retrieve container logs for a session.

Input Schema:

{
  "project": "string (required)",
  "session": "string (required)",
  "container": "string (optional)",
  "tail_lines": "integer (optional, max: 10000)"
}

Behavior:

• Retrieve logs via gateway endpoint (TBD)
• Default tail: 1000 lines
• Max tail: 10,000 lines

---

acp_get_session_transcript

Retrieve conversation history in JSON or Markdown format.

Input Schema:

{
  "project": "string (required)",
  "session": "string (required)",
  "format": "string (optional, default: 'json') - json|markdown"
}

Behavior:

• Get session data
• Extract transcript from session status
• Convert to requested format

---

acp_get_session_metrics

Get usage statistics (tokens, duration, tool calls).

Input Schema:

{
  "project": "string (required)",
  "session": "string (required)"
}

Behavior:

• Get session and transcript
• Calculate token count, tool calls, duration
• Return aggregated metrics

---

acp_label_resource / acp_unlabel_resource

Add/remove labels to/from sessions.

Label Format: acp.ambient-code.ai/label-{key}={value}

Input Schema (label):

{
  "resource_type": "string (required) - agenticsession",
  "name": "string (required)",
  "project": "string (required)",
  "labels": "object (required) - key-value pairs"
}

Behavior:

• Validate label keys/values (max 63 chars, alphanumeric + dash/underscore/dot)
• Apply via gateway API with label prefix

---

acp_bulk_stop_sessions

Stop multiple running sessions.

Input Schema:

{
  "project": "string (required)",
  "sessions": "array[string] (required, max 3)",
  "dry_run": "boolean (optional, default: false)"
}

Behavior:

• Validate bulk limit (max 3)
• For each session: patch with {"spec": {"stopped": true}}

---

acp_login

Authenticate to cluster.

Input Schema:

{
  "cluster": "string (required) - alias or server URL",
  "web": "boolean (optional, default: true)",
  "token": "string (optional)"
}

Behavior:

• Resolve cluster name to server URL
• Authenticate via gateway token exchange
• Return login status

---

acp_add_cluster

Add cluster to configuration file.

Input Schema:

{
  "name": "string (required)",
  "server": "string (required)",
  "description": "string (optional)",
  "default_project": "string (optional)",
  "set_default": "boolean (optional, default: false)"
}

Behavior:

• Validate inputs
• Add to clusters.yaml config
• Write with secure file permissions

---

acp_list_workflows

Discover available workflows.

Input Schema:

{
  "repo_url": "string (optional, default: ootb-ambient-workflows)"
}

Behavior:

• Query workflow repository
• Parse workflow definitions
• Return list of available workflows

---

Implementation Notes

• All new tools should use the httpx-based _request() method (not oc subprocess)
• Follow the existing pattern: client method → server dispatch → formatter
• Maintain bulk safety limits (MAX_BULK_ITEMS = 3)
• Support dry_run on all mutating operations
• Gateway API endpoints TBD — coordinate with public-api team

Related

• PR feat: authenticate via public-api gateway instead of OpenShift API #23: Replaced oc CLI with HTTP-based gateway auth
• PR feat: add acp_create_session tool to submit hpc-style jobs via mcp #26: Merged gateway architecture