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

Category	Tool	Description
Session	`acp_list_sessions`	List/filter sessions with advanced options
	`acp_delete_session`	Delete session with dry-run support
	`acp_restart_session`	Restart stopped sessions
	`acp_clone_session`	Clone session configuration
	`acp_update_session`	Update session metadata
Labels	`acp_label_resource`	Add labels to sessions
	`acp_unlabel_resource`	Remove labels from sessions
	`acp_list_sessions_by_label`	Find sessions by label
Bulk Ops	`acp_bulk_delete_sessions`	Delete multiple sessions (max 3)
	`acp_bulk_stop_sessions`	Stop multiple sessions (max 3)
	`acp_bulk_restart_sessions`	Restart multiple sessions (max 3)
	`acp_bulk_delete_sessions_by_label`	Delete sessions by label
Debug	`acp_get_session_logs`	Get container logs
	`acp_get_session_transcript`	Get conversation history
	`acp_get_session_metrics`	Get usage statistics
	`acp_export_session`	Export session data
Cluster	`acp_list_clusters`	List configured clusters
	`acp_whoami`	Check authentication status
	`acp_login`	Authenticate to cluster
	`acp_switch_cluster`	Switch cluster context
	`acp_add_cluster`	Add cluster to config
Workflows	`acp_list_workflows`	Discover available workflows
	`acp_create_session_from_template`	Create from template

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:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass (pytest)
Ensure code quality checks pass (make check)
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 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github/workflows		.github/workflows
demos		demos
src/mcp_acp		src/mcp_acp
tests		tests
utils		utils
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
API_REFERENCE.md		API_REFERENCE.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Makefile		Makefile
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SECURITY.md		SECURITY.md
TRIGGER_PHRASES.md		TRIGGER_PHRASES.md
check-config.sh		check-config.sh
clusters.yaml.example		clusters.yaml.example
pyproject.toml		pyproject.toml

ambient-code/mcp

Folders and files

Latest commit

History

Repository files navigation

MCP ACP Server

Quick Start

Overview

Features

Session Management

Label Management

Bulk Operations

Debugging & Monitoring

Cluster Management

Workflows

Installation

From PyPI (when published)

From Source

Configuration

1. Create Cluster Configuration

2. Configure MCP Client

3. Authenticate with OpenShift

Usage Examples

List Sessions with Filtering

Label Management

Delete Session with Dry-Run

Bulk Operations

Get Session Logs

Tool Reference

Quick Reference

Architecture

Security

Development

Running Tests

Code Quality

Documentation

Roadmap

Contributing

License

Support

Status

About

Resources

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 2

Uh oh!

Languages

Packages