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:

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

Tool Reference

For complete API specifications including input schemas, output formats, and behavior details, see API_REFERENCE.md.

Troubleshooting

"No authentication token available"

Your token is not configured. Either:

1. Add token: your-token-here to your cluster in ~/.config/acp/clusters.yaml
2. Set the ACP_TOKEN environment variable

"HTTP 401: Unauthorized"

Your token is expired or invalid. Get a new token from the ACP platform administrator.

"HTTP 403: Forbidden"

You don't have permission for this operation. Contact your ACP platform administrator.

"Direct Kubernetes API URLs (port 6443) are not supported"

You're using a direct K8s API URL. Use the public-api gateway URL instead:

• Wrong: https://api.cluster.example.com:6443
• Correct: https://public-api-ambient.apps.cluster.example.com

"mcp-acp: command not found"

Add Python user bin to PATH:

• macOS: export PATH="$HOME/Library/Python/3.*/bin:$PATH"
• Linux: export PATH="$HOME/.local/bin:$PATH"

Then restart your shell.

MCP Tools Not Showing in Claude

1. Check Claude Desktop logs: Help → View Logs
2. Verify config file syntax is valid JSON
3. Make sure mcp-acp is in PATH
4. Restart Claude Desktop completely (quit, not just close)

"Permission denied" on clusters.yaml

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

Architecture

• MCP SDK — Standard MCP protocol implementation (stdio transport)
• httpx — Async HTTP REST client for the public-api gateway
• Pydantic — Settings management and input validation
• Three-layer design — Server (tool dispatch) → Client (HTTP + validation) → Formatters (output)

See CLAUDE.md for complete system design.

Security

• Input Validation — DNS-1123 format validation for all resource names
• Gateway URL Enforcement — Direct K8s API URLs (port 6443) rejected
• Bearer Token Security — Tokens filtered from logs, sourced from config or environment
• Resource Limits — Bulk operations limited to 3 items with confirmation

See SECURITY.md for complete security documentation including threat model and best practices.

Development

# One-time setup
uv venv && uv pip install -e ".[dev]"

# Pre-commit workflow
uv run ruff format . && uv run ruff check . && uv run pytest tests/

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

# Build wheel
uvx --from build pyproject-build --installer uv

See CLAUDE.md for contributing guidelines.

Roadmap

Current implementation provides 26 tools. 3 tools remain planned:

• Session export (issue #28)
• Workflow management (issue #29)

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (uv run pytest tests/)
5. Ensure code quality checks pass (uv run ruff format . && uv run ruff check .)
6. Submit a pull request

Status

Code: Production-Ready | Tests: All Passing | Security: Input validation, gateway enforcement, token security | Tools: 26 implemented (3 more planned)

Documentation

• API_REFERENCE.md — Full API specifications for all 26 tools
• SECURITY.md — Security features, threat model, and best practices
• CLAUDE.md — System architecture and development guide

License

MIT License — See LICENSE file for details.

Support

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