Which integrations are available for this server?

Delegates agentic sessions to Kubernetes-hosted Claude agents running on the Ambient Code Platform, enabling creation and management of AI agent sessions, sending messages to sessions, and monitoring session status through OpenShift/Kubernetes cluster integration.

How do I use Ambient Code Platform MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Ambient Code Platform MCP Server list my agentic sessions in the development project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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/mcp-acp-v0.1.0/mcp_acp-0.1.0-py3-none-any.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: Use acp_whoami to check my authentication

Overview

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

Session Management: List, create, delete, restart, clone sessions
Bulk Operations: Efficiently manage multiple sessions at once
Advanced Filtering: Filter by status, age, display name, 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

acp_add_cluster: Add new cluster configurations
acp_bulk_delete_sessions: Delete multiple sessions at once
acp_bulk_stop_sessions: Stop multiple running sessions
acp_clone_session: Clone existing session configurations
acp_create_session_from_template: Create sessions from predefined templates
acp_delete_session: Delete sessions with dry-run preview
acp_export_session: Export session data for archival
acp_get_session_logs: Retrieve container logs for debugging
acp_get_session_metrics: Get usage statistics and analytics
acp_get_session_transcript: Retrieve conversation history
acp_list_clusters: List configured cluster aliases
acp_list_sessions: Enhanced filtering by status, display name, age, and sorting
acp_list_workflows: Discover available workflows
acp_login: Web-based authentication flow
acp_restart_session: Restart stopped sessions
acp_switch_cluster: Switch between configured clusters
acp_update_session: Update session metadata
acp_whoami: Check authentication status

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

Installation

From PyPI (when published)

From Source

git clone https://github.com/ambient-code/mcp claude mcp add mcp-acp -t stdio mcp/mcp_acp-0.1.0-py3-none-any.whl

Requirements:

Python 3.10+
OpenShift CLI (oc) installed and in PATH
Access to an OpenShift cluster with ACP

See USAGE_GUIDE.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

Usage Examples

List Sessions with Filtering

# List only running sessions acp_list_sessions(project="my-workspace", status="running") # List sessions older than 7 days acp_list_sessions(project="my-workspace", older_than="7d") # List sessions sorted by creation date acp_list_sessions(project="my-workspace", sort_by="created", limit=20)

Delete Session with Dry-Run

# Preview what would be deleted acp_delete_session(project="my-workspace", session="test-session", dry_run=True) # Actually delete acp_delete_session(project="my-workspace", session="test-session")

Bulk Operations

# Stop multiple sessions acp_bulk_stop_sessions( project="my-workspace", sessions=["session-1", "session-2", "session-3"] ) # Delete old sessions with dry-run acp_bulk_delete_sessions( project="my-workspace", sessions=["old-session-1", "old-session-2"], dry_run=True )

Get Session Logs

# Get logs from runner container acp_get_session_logs( project="my-workspace", session="debug-session", container="runner", tail_lines=100 )

See USAGE_GUIDE.md for 40+ detailed examples and workflow patterns.

Tool Reference

For complete API specifications, see API_REFERENCE.md.

Quick Reference

Tool	Description
`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_bulk_delete_sessions`	Delete multiple sessions
`acp_bulk_stop_sessions`	Stop multiple sessions
`acp_get_session_logs`	Get container logs
`acp_list_clusters`	List configured clusters
`acp_whoami`	Check authentication status
`acp_clone_session`	Clone session configuration
`acp_get_session_transcript`	Get conversation history
`acp_update_session`	Update session metadata
`acp_export_session`	Export session data
`acp_get_session_metrics`	Get usage statistics
`acp_list_workflows`	Discover workflows
`acp_create_session_from_template`	Create from template
`acp_login`	Authenticate to cluster
`acp_switch_cluster`	Switch cluster context
`acp_add_cluster`	Add cluster to config

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 ARCHITECTURE.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 DEVELOPMENT.md for contributing guidelines.

Documentation

USAGE_GUIDE.md - Complete usage guide with examples
API_REFERENCE.md - Full API specifications for all 19 tools
ARCHITECTURE.md - System architecture and design
SECURITY.md - Security features and best practices
DEVELOPMENT.md - Development and contributing guide
CLEANROOM_SPEC.md - Re-implementation specification

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 DEVELOPMENT.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:

USAGE_GUIDE.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: ✅ 19 tools fully implemented

Ready for production use 🚀

Ambient Code Platform MCP Server