ACP MCP Server Enhancements: Session Management, Authentication, and Power User Features

[jeremyeder]

Context

During active usage of the ACP (Ambient Code Platform) MCP server, several significant gaps and improvement opportunities were identified. This issue tracks all proposed enhancements to improve the developer experience.

Source: Feature Request Gist
Date: 2026-01-29
Author: @jeremyeder

---

Current MCP Tools (Baseline)

Tool	Purpose
acp_list_projects	List projects/namespaces
acp_list_sessions	List sessions in a project
acp_get_session	Get session details
acp_get_events	Get session events
acp_whoami	Check auth status
acp_create_session	Create new session
acp_send_message	Send message to session
acp_stop_session	Stop a running session

---

🔴 P0 - High Priority (Immediate Gaps)

1. acp_delete_session

Problem: No way to delete sessions via MCP. Currently requires manual oc delete agenticsession <name> -n <namespace>.

Proposed API:

acp_delete_session(project: str, session: str) -> {deleted: bool, message: str}

2. acp_list_sessions Enhanced Filtering

Problem: Must parse full JSON output to find specific sessions. Need server-side filtering support.

Proposed Parameters:

acp_list_sessions(
  project: str,
  status?: "stopped" | "running" | "creating" | "failed",
  has_display_name?: bool,
  older_than?: str,  # e.g., "7d", "24h"
  sort_by?: "created" | "stopped" | "name",
  limit?: int
)

3. acp_login (Web-based Authentication)

Problem: Current auth flow requires manual token retrieval from OpenShift console, then oc login --token=.... Token expiry requires repeating this painful process.

Proposed API:

acp_login(
  cluster: str,  # alias name or full server URL
  web?: bool = true,  # use web login flow
  token?: str  # alternative: direct token auth
) -> {
  user: str,
  cluster: str,
  server: str,
  message: str
}

Behavior:

1. Look up cluster alias in ~/.config/acp/clusters.yaml
2. Run oc login --web --server=<server_url>
3. Browser opens for OAuth flow
4. Return success with user info

---

🟡 P1 - Medium Priority (Workflow Improvements)

4. acp_restart_session

Problem: Cannot resume a stopped session without recreating from scratch.

Proposed API:

acp_restart_session(project: str, session: str) -> {status: str, message: str}

5. acp_bulk_delete_sessions

Use case: Clean up multiple stopped sessions at once.

Proposed API:

acp_bulk_delete_sessions(
  project: str,
  sessions: list[str]
) -> {deleted: list[str], failed: list[{session: str, error: str}]}

6. acp_list_clusters

Use case: Show available cluster aliases from config.

Proposed API:

acp_list_clusters() -> list[{
  name: str,
  server: str,
  description: str,
  is_current: bool,
  is_default: bool
}]

7. acp_get_session_logs

Use case: Debug failed or misbehaving sessions.

Proposed API:

acp_get_session_logs(
  project: str, 
  session: str,
  container?: str,  # "runner", "sidecar", etc.
  tail_lines?: int
) -> {logs: str}

8. acp_bulk_stop_sessions

Use case: Stop multiple running sessions at once.

Proposed API:

acp_bulk_stop_sessions(
  project: str,
  sessions: list[str]
) -> {stopped: list[str], failed: list[{session: str, error: str}]}

---

🟢 P2 - Nice to Have (Power User Features)

9. acp_clone_session

Use case: Duplicate session config (repos, workflow, LLM settings) to create new session.

Proposed API:

acp_clone_session(
  project: str,
  source_session: str,
  new_display_name: str
) -> {session: str, message: str}

10. acp_get_session_transcript

Use case: Retrieve full conversation history without direct S3 access.

Proposed API:

acp_get_session_transcript(
  project: str,
  session: str,
  format?: "json" | "markdown"
) -> {transcript: str | list}

11. acp_update_session

Use case: Update display name or other mutable fields on existing session.

Proposed API:

acp_update_session(
  project: str,
  session: str,
  display_name?: str,
  timeout?: int
) -> {updated: bool, session: object}

12. acp_export_session

Use case: Export session data (config + transcript) for archival or sharing.

Proposed API:

acp_export_session(
  project: str,
  session: str
) -> {config: object, transcript: list, metadata: object}

---

🔵 P3 - Future Enhancements

13. acp_get_session_metrics

Use case: Token usage, duration, tool call statistics.

Proposed API:

acp_get_session_metrics(
  project: str,
  session: str
) -> {
  token_count: int,
  duration_seconds: int,
  tool_calls: {tool_name: count},
  message_count: int
}

14. acp_list_workflows

Use case: Discover available workflows without knowing git repo structure.

Proposed API:

acp_list_workflows(
  repo_url?: str  # defaults to ootb-ambient-workflows
) -> list[{name: str, path: str, description: str}]

15. acp_create_session_from_template

Use case: Predefined session configs for common patterns.

Proposed API:

acp_create_session_from_template(
  project: str,
  template: "triage" | "bugfix" | "feature" | "exploration",
  display_name: str,
  repos?: list[str]
) -> {session: str}

16. acp_watch_events

Use case: Stream events in real-time for monitoring.

Note: May require SSE/websocket support in MCP protocol.

---

🔐 OpenShift Authentication Enhancements

Cluster Configuration File

Store named cluster configs in ~/.config/acp/clusters.yaml:

clusters:
  vteam-stage:
    server: https://api.vteam-stage.7fpc.p3.openshiftapps.com:443
    description: "V-Team Staging Environment"
    default_project: jeder-workspace
    
  vteam-prod:
    server: https://api.vteam-prod.xxxx.p3.openshiftapps.com:443
    description: "V-Team Production"
    default_project: jeder-workspace

default_cluster: vteam-stage

Additional Auth Tools

acp_switch_cluster - Switch between already-authenticated clusters

acp_switch_cluster(cluster: str) -> {previous: str, current: str, user: str}

acp_add_cluster - Register a new cluster alias

acp_add_cluster(
  name: str,
  server: str,
  description?: str,
  default_project?: str,
  set_default?: bool
) -> {added: bool, cluster: object}

Enhanced acp_whoami

Expand output to include:

{
  "user": "jeder",
  "cluster": "vteam-stage",
  "server": "https://api.vteam-stage...",
  "project": "jeder-workspace",
  "token_expires": "2026-01-30T06:00:00Z",
  "token_valid": true
}

Auto-Prompt on Auth Failure

When any MCP tool fails with auth error:

1. Detect the error pattern
2. Offer: "Authentication failed for vteam-stage. Run acp_login(cluster='vteam-stage') to re-authenticate?"
3. Or auto-trigger login flow if configured

---

Implementation Roadmap

Phase 1: Core Gaps (P0)

• acp_delete_session (Low effort)
• acp_list_sessions filters (Medium effort)
• acp_login with web flow (Medium effort)

Phase 2: Workflow Essentials (P1)

• acp_restart_session (Low effort)
• acp_bulk_delete_sessions (Low effort)
• acp_list_clusters (Low effort)
• acp_get_session_logs (Medium effort)
• acp_bulk_stop_sessions (Low effort)

Phase 3: Power User Features (P2)

• acp_clone_session (Medium effort)
• acp_get_session_transcript (Medium effort)
• acp_update_session (Low effort)
• acp_export_session (Medium effort)

Phase 4: Advanced Features (P3)

• acp_get_session_metrics (Medium effort)
• acp_list_workflows (Low effort)
• acp_create_session_from_template (Medium effort)
• acp_watch_events (High effort - requires protocol changes)

Phase 5: Auth Experience Polish

• acp_switch_cluster (Low effort)
• acp_add_cluster (Low effort)
• Enhanced acp_whoami (Low effort)
• Auto-prompt on auth failure (Medium effort)
• Token expiry detection (Medium effort)

---

Next Steps

1. Design API contracts for authentication tools
2. Prototype acp_login --web flow to validate UX
3. Implement P0 features (delete, filtering, web login)
4. Gather user feedback before proceeding to P1/P2

---

Success Metrics

• Eliminate manual oc commands for common operations
• Reduce auth friction from multi-step manual flow to single MCP command
• Enable bulk operations for session lifecycle management
• Provide power users with debugging and analytics capabilities

🤖 Generated with Claude Code

[jeremyeder]

Safety Requirement: Destructive Operation Confirmations

Default Behavior for Delete/Bulk Operations:

The following operations should require explicit confirmation by default to prevent accidental data loss:

Operations Requiring Confirmation

1. acp_delete_session

   • Should require confirm=true parameter
   • Or interactive prompt: "Delete session '{session}' in project '{project}'? (yes/no)"

2. acp_bulk_delete_sessions

   • MUST show list of sessions to be deleted
   • Require explicit confirmation before proceeding
   • Example: "About to delete 5 sessions: [list]. Proceed? (yes/no)"

3. acp_bulk_stop_sessions

   • Less critical than delete, but should still confirm
   • Show count and list before stopping

Proposed API Pattern

# Require explicit confirmation flag
acp_delete_session(
  project: str, 
  session: str,
  confirm: bool = False  # Must be explicitly set to True
) -> {deleted: bool, message: str}

# Or use an interactive confirmation prompt
acp_bulk_delete_sessions(
  project: str,
  sessions: list[str],
  force: bool = False  # Bypass confirmation (dangerous!)
) -> {
  confirmed: bool,
  deleted: list[str], 
  failed: list[{session: str, error: str}]
}

Alternative: Dry-Run Mode

Consider adding dry_run=true parameter that shows what WOULD be deleted without actually deleting:

acp_bulk_delete_sessions(
  project="jeder-workspace",
  sessions=["session-1", "session-2"],
  dry_run=True
)
# Returns: {would_delete: ["session-1", "session-2"], count: 2}

This prevents catastrophic mistakes while still allowing power users to script operations when needed.

[jeremyeder]

Yes - dry-run mode makes sense.