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. Session Context Management (5 new tools)

Problem: No way to manipulate session context (repos, workflows, MCP servers) after session creation. Sessions are immutable once created.

Proposed APIs:

acp_add_repo

acp_add_repo(
  project: str,
  session: str,
  repo_url: str,
  branch?: str = "main",
  auto_push?: bool = false
) -> {added: bool, reconciled: bool, message: str}

acp_remove_repo

acp_remove_repo(
  project: str,
  session: str,
  repo_url: str
) -> {removed: bool, message: str}

acp_list_repos

acp_list_repos(
  project: str,
  session: str
) -> {repos: list[{url: str, branch: str, status: str, cloned_at: str}]}

acp_set_workflow

acp_set_workflow(
  project: str,
  session: str,
  workflow_git_url: str,
  workflow_branch: str,
  workflow_path: str
) -> {applied: bool, message: str}

acp_clear_workflow

acp_clear_workflow(
  project: str,
  session: str
) -> {cleared: bool, message: str}

Use Cases:

• Add additional repos to running session for broader context
• Remove repos to reduce context size and improve performance
• Switch workflows mid-session (e.g., from exploration to bugfix)
• Clear workflow to return to general-purpose mode

2. MCP Server Management (5 new tools)

Problem: MCP servers are configured at platform level, not per-session. No way to enable/disable specific MCP servers for individual sessions.

Proposed APIs:

acp_list_available_mcps

acp_list_available_mcps(
  project: str
) -> {mcps: list[{name: str, description: str, tools: list[str]}]}

acp_list_session_mcps

acp_list_session_mcps(
  project: str,
  session: str
) -> {enabled_mcps: list[str], available_mcps: list[str]}

acp_enable_mcp

acp_enable_mcp(
  project: str,
  session: str,
  mcp_name: str
) -> {enabled: bool, message: str}

acp_disable_mcp

acp_disable_mcp(
  project: str,
  session: str,
  mcp_name: str
) -> {disabled: bool, message: str}

acp_configure_mcp

acp_configure_mcp(
  project: str,
  session: str,
  mcp_name: str,
  config: dict  # MCP-specific configuration
) -> {configured: bool, message: str}

Use Cases:

• Enable GitHub MCP only when working with GitHub repos
• Disable expensive MCPs (like web search) for cost control
• Configure MCP-specific settings (API keys, rate limits) per session
• Experiment with different MCP combinations for different workflows

Implementation Notes:

• MCP changes should take effect immediately (no session restart)
• Should validate MCP availability before enabling
• Should handle MCP dependencies (e.g., if MCP A requires MCP B)
• Should track MCP usage metrics per session

3. 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}

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

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

6. 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}

7. 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}]}

8. 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
}]

9. 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}

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

11. 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}

12. 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}

13. 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}

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

15. 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
}

16. 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}]

17. 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}

18. 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) - 15 tools

• Session Context Management (5 tools)
  • acp_add_repo
  • acp_remove_repo
  • acp_list_repos
  • acp_set_workflow
  • acp_clear_workflow
• MCP Server Management (5 tools)
  • acp_list_available_mcps
  • acp_list_session_mcps
  • acp_enable_mcp
  • acp_disable_mcp
  • acp_configure_mcp
• acp_delete_session (Low effort)
• acp_list_sessions filters (Medium effort)
• acp_login with web flow (Medium effort)

Phase 2: Workflow Essentials (P1) - 5 tools

• 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) - 4 tools

• 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) - 4 tools

• 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 - 3 tools

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

---

Summary

Total New Tools: 31

• P0 (High Priority): 15 tools
• P1 (Medium Priority): 5 tools
• P2 (Nice to Have): 4 tools
• P3 (Future): 4 tools
• Auth Enhancements: 3 tools

Key Themes:

1. Dynamic Session Context - Add/remove repos, workflows, and MCP servers on the fly
2. Session Lifecycle - Delete, restart, bulk operations
3. Authentication UX - Web-based login, cluster aliases, auto-recovery
4. Power User Tools - Logs, transcripts, metrics, cloning
5. Developer Experience - Filtering, sorting, templates

---

Next Steps

1. Review and prioritize with ACP team
2. Design API contracts for P0 features
3. Prototype context management (repos/workflows/MCPs)
4. Implement P0 features in order of impact
5. Gather user feedback before proceeding to P1/P2

---

Success Metrics

• Eliminate manual oc commands for common operations
• Enable dynamic session context manipulation without restarts
• 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.