MCP ACP Server

A Model Context Protocol (MCP) server for managing Ambient Code Platform (ACP) sessions via the public-api gateway.

---

Table of Contents

• Quick Start
• Features
• Installation
• Configuration
• Usage
• Tool Reference
• Troubleshooting
• Architecture
• Security
• Development
• Roadmap
• Contributing
• Status

---

Quick Start

# Install
git clone https://github.com/ambient-code/mcp
cd mcp
pip install .    # installs the 'mcp-acp' command

# Configure
mkdir -p ~/.config/acp
cat > ~/.config/acp/clusters.yaml <<EOF
clusters:
  my-cluster:
    server: https://public-api-ambient.apps.your-cluster.example.com
    token: your-bearer-token-here
    default_project: my-workspace
default_cluster: my-cluster
EOF
chmod 600 ~/.config/acp/clusters.yaml

Then add to your MCP client (Claude Desktop, Claude Code, or uvx) and try:

List my ACP sessions

---

Features

Session Management

Observability

Labels

Bulk Operations

Cluster Management

Safety Features:

• Dry-Run Mode — All mutating operations support dry_run for safe preview before executing
• Bulk Operation Limits — Maximum 3 items per bulk operation with confirmation requirement
• Label Validation — Labels must be 1-63 alphanumeric characters, dashes, dots, or underscores

---

Installation

From Source (end users)

git clone https://github.com/ambient-code/mcp
cd mcp
pip install .    # installs the 'mcp-acp' command

From Wheel

Requires make to be installed.

# "make install" sets up the dev environment (.venv + dependencies),
# which "make build" then uses to produce the wheel in dist/
make install
make build
pip install dist/mcp_acp-*.whl

Development Install (contributors)

git clone https://github.com/ambient-code/mcp
cd mcp
uv venv
uv pip install -e ".[dev]"

Virtual Environment Install

On some Linux distributions (Debian, Ubuntu, Fedora 38+), PEP 668 prevents pip install into the system Python. If you get an "externally-managed-environment" error, install into a virtual environment instead:

git clone https://github.com/ambient-code/mcp
cd mcp
python3 -m venv .venv
source .venv/bin/activate
pip install .

Note that the mcp-acp command will only be available inside the venv. To use it from an MCP client like Claude Code, reference the full path:

claude mcp add mcp-acp -t stdio /full/path/to/mcp/.venv/bin/mcp-acp

Requirements:

• Python 3.12+
• Bearer token for the ACP public-api gateway
• Access to an ACP cluster

---

Configuration

Cluster Config

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

clusters:
  vteam-stage:
    server: https://public-api-ambient.apps.vteam-stage.example.com
    token: your-bearer-token-here
    description: "V-Team Staging Environment"
    default_project: my-workspace

  vteam-prod:
    server: https://public-api-ambient.apps.vteam-prod.example.com
    token: your-bearer-token-here
    description: "V-Team Production"
    default_project: my-workspace

default_cluster: vteam-stage

Then secure the file:

chmod 600 ~/.config/acp/clusters.yaml

Authentication

Add your Bearer token to each cluster entry under the token field, or set the ACP_TOKEN environment variable:

export ACP_TOKEN=your-bearer-token-here

Get your token from the ACP platform administrator or the gateway's authentication endpoint.

Claude Desktop

Edit your configuration file:

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

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

After editing, completely quit and restart Claude Desktop (not just close the window).

Claude Code (CLI)

claude mcp add mcp-acp -t stdio mcp-acp

Using uvx

uvx provides zero-install execution — no global Python pollution, auto-caching, and fast startup.

# Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

Claude Desktop config for uvx:

{
  "mcpServers": {
    "acp": {
      "command": "uvx",
      "args": ["mcp-acp"]
    }
  }
}

For a local wheel (before PyPI publish):

{
  "mcpServers": {
    "acp": {
      "command": "uvx",
      "args": ["--from", "/full/path/to/dist/mcp_acp-0.3.0-py3-none-any.whl", "mcp-acp"]
    }
  }
}

---

Usage

Examples

# List sessions
List my ACP sessions
Show running sessions in my-workspace
List sessions older than 7 days in my-workspace
List sessions sorted by creation date, limit 20

# Session details
Get details for ACP session session-name
Show AgenticSession session-name in my-workspace

# Create a session
Create a new ACP session with prompt "Run all unit tests and report results"

# Create from template
Create an ACP session from the bugfix template called "fix-auth-issue"

# Restart / clone
Restart ACP session my-stopped-session
Clone ACP session my-session as "my-session-v2"

# Update session metadata
Update ACP session my-session display name to "Production Test Runner"

# Observability
Show logs for ACP session my-session
Get transcript for ACP session my-session in markdown format
Show metrics for ACP session my-session

# Labels
Label ACP session my-session with env=staging and team=platform
Remove label env from ACP session my-session
List ACP sessions with label team=platform

# Delete with dry-run (safe!)
Delete test-session from my-workspace in dry-run mode

# Actually delete
Delete test-session from my-workspace

# Bulk operations (dry-run first)
Delete these sessions: session-1, session-2, session-3 from my-workspace (dry-run first)
Stop all sessions with label env=test
Restart sessions with label team=platform

# Cluster operations
Check my ACP authentication
List my ACP clusters
Switch to ACP cluster vteam-prod
Login to ACP cluster vteam-stage with token

Trigger Keywords

Include one of these keywords so your MCP client routes the request to ACP: ACP, ambient, AgenticSession, or use tool names directly (e.g., acp_list_sessions, acp_whoami). Without a keyword, generic phrases like "list sessions" may not trigger the server.

Quick Reference

---