MCP ACP Server

A Model Context Protocol (MCP) server for managing Ambient Code Platform (ACP) sessions on OpenShift/Kubernetes clusters.

Based on template-agent

Quick Start

Get started in 5 minutes:

# Install
git clone https://github.com/ambient-code/mcp
claude mcp add mcp-acp -t stdio mcp/dist/mcp_acp-*.whl

# Configure
mkdir -p ~/.config/acp
cat > ~/.config/acp/clusters.yaml <<EOF
clusters:
  my-cluster:
    server: https://api.your-cluster.example.com:443
    default_project: my-workspace
default_cluster: my-cluster
EOF

# Authenticate
oc login --server=https://api.your-cluster.example.com:443

# Add to Claude Desktop config
{
  "mcpServers": {
    "acp": {
      "command": "mcp-acp"
    }
  }
}

First Command: List my ambient sessions that are older than a week

Overview

This MCP server provides 27 comprehensive tools for interacting with the Ambient Code Platform, enabling:

• Session Management: List, create, delete, restart, clone sessions

• Label Management: Tag and organize sessions with custom labels

• Bulk Operations: Efficiently manage multiple sessions at once

• Advanced Filtering: Filter by status, age, display name, labels, and more

• Debugging: Retrieve logs, transcripts, and metrics

• Cluster Management: Multi-cluster support with easy switching

• Safety First: Dry-run mode on all mutating operations

Security: This server implements comprehensive security measures including input validation, command injection prevention, timeout controls, and resource limits. See SECURITY.md for details.

Features

Session Management

• acp_list_sessions: Enhanced filtering by status, display name, age, labels, and sorting

• acp_delete_session: Delete sessions with dry-run preview

• acp_restart_session: Restart stopped sessions

• acp_clone_session: Clone existing session configurations

• acp_create_session_from_template: Create sessions from predefined templates

• acp_update_session: Update session metadata

Label Management

• acp_label_resource: Add labels to sessions or other resources

• 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

• acp_bulk_delete_sessions: Delete multiple sessions with confirmation

• acp_bulk_stop_sessions: Stop multiple running sessions with confirmation

• acp_bulk_delete_sessions_by_label: Delete sessions by label selector

• acp_bulk_stop_sessions_by_label: Stop sessions by label selector

• acp_bulk_restart_sessions: Restart multiple sessions (max 3)

• acp_bulk_restart_sessions_by_label: Restart sessions by label selector

Debugging & Monitoring

• acp_get_session_logs: Retrieve container logs for debugging

• acp_get_session_transcript: Retrieve conversation history

• acp_get_session_metrics: Get usage statistics and analytics

• acp_export_session: Export session data for archival

Cluster Management

• acp_list_clusters: List configured cluster aliases

• acp_whoami: Check authentication status

• acp_login: Web-based authentication flow

• acp_switch_cluster: Switch between configured clusters

• acp_add_cluster: Add new cluster configurations

Workflows

• acp_list_workflows: Discover available workflows

Safety Features:

• Dry-Run Mode: All mutating operations support a dry_run parameter for safe preview before executing

• Bulk Operation Limits: Maximum 3 items per bulk operation with confirmation requirement

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

Installation

From PyPI (when published)

From Source

git clone https://github.com/ambient-code/mcp
pip install dist/mcp_acp-*.whl

Requirements:

• Python 3.10+

• OpenShift CLI (oc) installed and in PATH

• Access to an OpenShift cluster with ACP

See QUICKSTART.md for detailed installation instructions.

Configuration

1. Create Cluster Configuration

Create ~/.config/acp/clusters.yaml:

clusters:
  vteam-stage:
    server: https://api.vteam-stage.xxxx.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

2. Configure MCP Client

For Claude Desktop, edit your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

Add the ACP server:

{
  "mcpServers": {
    "acp": {
      "command": "mcp-acp",
      "args": [],
      "env": {
        "ACP_CLUSTER_CONFIG": "${HOME}/.config/acp/clusters.yaml"
      }
    }
  }
}

3. Authenticate with OpenShift

oc login --server=https://api.your-cluster.example.com:443

Note: Direct OpenShift CLI authentication is required for testing until the frontend API is available (tracked in PR #558).

Usage Examples

List Sessions with Filtering

# List only running sessions
List running sessions in my-workspace

# List sessions older than 7 days
Show me sessions older than 7 days in my-workspace

# List sessions by label
List sessions with env=test and team=qa labels in my-workspace

# List sessions sorted by creation date
List sessions in my-workspace, sorted by creation date, limit 20

Label Management

# Add labels to a session
Add env=test and team=qa labels to my-session in my-workspace

# List sessions by label
List sessions with env=test label in my-workspace

# Bulk delete sessions by label
Delete all sessions with env=test label in my-workspace (dry-run first)

Delete Session with Dry-Run

# Preview what would be deleted
Delete test-session from my-workspace in dry-run mode

# Actually delete
Delete test-session from my-workspace

Bulk Operations

# Stop multiple sessions
Stop session-1, session-2, and session-3 in my-workspace

# Delete old sessions with dry-run
Delete old-session-1 and old-session-2 from my-workspace in dry-run mode

Get Session Logs

# Get logs from runner container
Get logs from debug-session in my-workspace, runner container, last 100 lines

See QUICKSTART.md for detailed examples and workflow patterns.

Tool Reference

For complete API specifications, see API_REFERENCE.md.

Quick Reference

Architecture

The server is built using:

• MCP SDK: Standard MCP protocol implementation

• OpenShift CLI: Underlying oc commands for ACP operations

• Async I/O: Non-blocking operations for performance

• YAML Configuration: Flexible cluster management

See CLAUDE.md for complete system design.

Security

This server implements defense-in-depth security:

• Input Validation: DNS-1123 format validation for all resource names

• Command Injection Prevention: Secure subprocess execution (never shell=True)

• Resource Exhaustion Protection: Timeouts and limits on all operations

• Secure Temporary Files: Random prefixes, 0600 permissions

• Path Traversal Prevention: Configuration and workflow file validation

• Resource Type Whitelist: Only agenticsession, pods, event resources

• Sensitive Data Filtering: Tokens/passwords removed from logs

See SECURITY.md for complete security documentation.

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/mcp_acp --cov-report=html

# Run security tests
pytest tests/test_security.py -v

Code Quality

# Format code
black src/ tests/
ruff check src/ tests/

# Type checking
mypy src/

# All checks
make check

See CLAUDE.md for contributing guidelines.

Documentation

• QUICKSTART.md - Complete usage guide with examples

• API_REFERENCE.md - Full API specifications for all 27 tools

• CLAUDE.md - System architecture and design

• SECURITY.md - Security features and best practices

• CLAUDE.md - Development and contributing guide

Roadmap

Current implementation provides all planned features (19 tools). Future enhancements may include:

• Rate Limiting: Per-client request limits for HTTP exposure

• Audit Logging: Structured audit trail and SIEM integration

• Enhanced Authentication: OAuth2/OIDC support, MFA

• Network Security: mTLS for MCP transport, certificate pinning

• Advanced Metrics: Cost analysis, performance tracking

See the GitHub issue tracker for planned features and community requests.

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Add tests for new functionality

4. Ensure all tests pass (pytest)

5. Ensure code quality checks pass (make check)

6. Submit a pull request

See CLAUDE.md for detailed guidelines.

License

MIT License - See LICENSE file for details

Support

For issues and feature requests, please use the GitHub issue tracker.

For usage questions, see:

• QUICKSTART.md - Complete usage guide

• API_REFERENCE.md - API specifications

• SECURITY.md - Security features

Status

Code: ✅ Production-Ready Tests: ✅ All Passing (13/13 security tests) Documentation: ✅ Complete Security: ✅ Hardened with defense-in-depth Tools: ✅ 27 tools fully implemented Features: ✅ Label management, bulk operations, advanced filtering

Ready for production use 🚀