{"id":35882908,"url":"https://github.com/ambient-code/mcp","last_synced_at":"2026-02-16T07:18:49.434Z","repository":{"id":332416792,"uuid":"1130433864","full_name":"ambient-code/mcp","owner":"ambient-code","description":"MCP server for Ambient Code Platform - delegate agentic sessions to Kubernetes-hosted Claude agents","archived":false,"fork":false,"pushed_at":"2026-01-08T20:31:49.000Z","size":83,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T20:40:43.998Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ambient-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-08T13:56:22.000Z","updated_at":"2026-01-12T14:43:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ambient-code/mcp","commit_stats":null,"previous_names":["ambient-code/mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ambient-code/mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ambient-code","download_url":"https://codeload.github.com/ambient-code/mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fmcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28579087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T17:42:58.221Z","status":"ssl_error","status_checked_at":"2026-01-19T17:40:54.158Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-08T19:18:36.628Z","updated_at":"2026-02-16T07:18:49.412Z","avatar_url":"https://github.com/ambient-code.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP ACP Server\n\nA Model Context Protocol (MCP) server for managing Ambient Code Platform (ACP) sessions via the public-api gateway.\n\n---\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Tool Reference](#tool-reference)\n- [Troubleshooting](#troubleshooting)\n- [Architecture](#architecture)\n- [Security](#security)\n- [Development](#development)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [Status](#status)\n\n---\n\n## Quick Start\n\n```bash\n# Install\ngit clone https://github.com/ambient-code/mcp\npip install dist/mcp_acp-*.whl\n\n# Configure\nmkdir -p ~/.config/acp\ncat \u003e ~/.config/acp/clusters.yaml \u003c\u003cEOF\nclusters:\n  my-cluster:\n    server: https://public-api-ambient.apps.your-cluster.example.com\n    token: your-bearer-token-here\n    default_project: my-workspace\ndefault_cluster: my-cluster\nEOF\nchmod 600 ~/.config/acp/clusters.yaml\n```\n\nThen add to your MCP client ([Claude Desktop](#claude-desktop), [Claude Code](#claude-code-cli), or [uvx](#using-uvx)) and try:\n\n```\nList my ACP sessions\n```\n\n---\n\n## Features\n\n### Session Management\n\n| Tool | Description |\n|------|-------------|\n| `acp_list_sessions` | List/filter sessions by status, age, with sorting and limits |\n| `acp_get_session` | Get detailed session information by ID |\n| `acp_create_session` | Create sessions with custom prompts, repos, model selection, and timeout |\n| `acp_create_session_from_template` | Create sessions from predefined templates (triage/bugfix/feature/exploration) |\n| `acp_delete_session` | Delete sessions with dry-run preview |\n| `acp_restart_session` | Restart a stopped session |\n| `acp_clone_session` | Clone an existing session's configuration into a new session |\n| `acp_update_session` | Update session metadata (display name, timeout) |\n\n### Observability\n\n| Tool | Description |\n|------|-------------|\n| `acp_get_session_logs` | Retrieve container logs for a session |\n| `acp_get_session_transcript` | Retrieve conversation history (JSON or Markdown) |\n| `acp_get_session_metrics` | Get usage statistics (tokens, duration, tool calls) |\n\n### Labels\n\n| Tool | Description |\n|------|-------------|\n| `acp_label_resource` | Add labels to a session for organizing and filtering |\n| `acp_unlabel_resource` | Remove labels from a session by key |\n| `acp_list_sessions_by_label` | List sessions matching label selectors |\n| `acp_bulk_label_resources` | Add labels to multiple sessions (max 3) |\n| `acp_bulk_unlabel_resources` | Remove labels from multiple sessions (max 3) |\n\n### Bulk Operations\n\n| Tool | Description |\n|------|-------------|\n| `acp_bulk_delete_sessions` | Delete multiple sessions (max 3) with confirmation and dry-run |\n| `acp_bulk_stop_sessions` | Stop multiple running sessions (max 3) |\n| `acp_bulk_restart_sessions` | Restart multiple stopped sessions (max 3) |\n| `acp_bulk_delete_sessions_by_label` | Delete sessions matching label selectors (max 3 matches) |\n| `acp_bulk_stop_sessions_by_label` | Stop sessions matching label selectors (max 3 matches) |\n| `acp_bulk_restart_sessions_by_label` | Restart sessions matching label selectors (max 3 matches) |\n\n### Cluster Management\n\n| Tool | Description |\n|------|-------------|\n| `acp_list_clusters` | List configured cluster aliases |\n| `acp_whoami` | Check current configuration and authentication status |\n| `acp_switch_cluster` | Switch between configured clusters |\n| `acp_login` | Authenticate to a cluster with a Bearer token |\n\n**Safety Features:**\n\n- **Dry-Run Mode** — All mutating operations support `dry_run` for safe preview before executing\n- **Bulk Operation Limits** — Maximum 3 items per bulk operation with confirmation requirement\n- **Label Validation** — Labels must be 1-63 alphanumeric characters, dashes, dots, or underscores\n\n---\n\n## Installation\n\n### From Wheel\n\n```bash\npip install dist/mcp_acp-*.whl\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/ambient-code/mcp\ncd mcp\nuv pip install -e \".[dev]\"\n```\n\n**Requirements:**\n\n- Python 3.10+\n- Bearer token for the ACP public-api gateway\n- Access to an ACP cluster\n\n---\n\n## Configuration\n\n### Cluster Config\n\nCreate `~/.config/acp/clusters.yaml`:\n\n```yaml\nclusters:\n  vteam-stage:\n    server: https://public-api-ambient.apps.vteam-stage.example.com\n    token: your-bearer-token-here\n    description: \"V-Team Staging Environment\"\n    default_project: my-workspace\n\n  vteam-prod:\n    server: https://public-api-ambient.apps.vteam-prod.example.com\n    token: your-bearer-token-here\n    description: \"V-Team Production\"\n    default_project: my-workspace\n\ndefault_cluster: vteam-stage\n```\n\nThen secure the file:\n\n```bash\nchmod 600 ~/.config/acp/clusters.yaml\n```\n\n### Authentication\n\nAdd your Bearer token to each cluster entry under the `token` field, or set the `ACP_TOKEN` environment variable:\n\n```bash\nexport ACP_TOKEN=your-bearer-token-here\n```\n\nGet your token from the ACP platform administrator or the gateway's authentication endpoint.\n\n### Claude Desktop\n\nEdit your configuration file:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Linux**: `~/.config/claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"acp\": {\n      \"command\": \"mcp-acp\",\n      \"args\": [],\n      \"env\": {\n        \"ACP_CLUSTER_CONFIG\": \"${HOME}/.config/acp/clusters.yaml\"\n      }\n    }\n  }\n}\n```\n\nAfter editing, **completely quit and restart Claude Desktop** (not just close the window).\n\n### Claude Code (CLI)\n\n```bash\nclaude mcp add mcp-acp -t stdio mcp-acp\n```\n\n### Using uvx\n\n[uvx](https://docs.astral.sh/uv/) provides zero-install execution — no global Python pollution, auto-caching, and fast startup.\n\n```bash\n# Install uv (if needed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nClaude Desktop config for uvx:\n\n```json\n{\n  \"mcpServers\": {\n    \"acp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-acp\"]\n    }\n  }\n}\n```\n\nFor a local wheel (before PyPI publish):\n\n```json\n{\n  \"mcpServers\": {\n    \"acp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"/full/path/to/dist/mcp_acp-0.1.0-py3-none-any.whl\", \"mcp-acp\"]\n    }\n  }\n}\n```\n\n---\n\n## Usage\n\n### Examples\n\n```\n# List sessions\nList my ACP sessions\nShow running sessions in my-workspace\nList sessions older than 7 days in my-workspace\nList sessions sorted by creation date, limit 20\n\n# Session details\nGet details for ACP session session-name\nShow AgenticSession session-name in my-workspace\n\n# Create a session\nCreate a new ACP session with prompt \"Run all unit tests and report results\"\n\n# Create from template\nCreate an ACP session from the bugfix template called \"fix-auth-issue\"\n\n# Restart / clone\nRestart ACP session my-stopped-session\nClone ACP session my-session as \"my-session-v2\"\n\n# Update session metadata\nUpdate ACP session my-session display name to \"Production Test Runner\"\n\n# Observability\nShow logs for ACP session my-session\nGet transcript for ACP session my-session in markdown format\nShow metrics for ACP session my-session\n\n# Labels\nLabel ACP session my-session with env=staging and team=platform\nRemove label env from ACP session my-session\nList ACP sessions with label team=platform\n\n# Delete with dry-run (safe!)\nDelete test-session from my-workspace in dry-run mode\n\n# Actually delete\nDelete test-session from my-workspace\n\n# Bulk operations (dry-run first)\nDelete these sessions: session-1, session-2, session-3 from my-workspace (dry-run first)\nStop all sessions with label env=test\nRestart sessions with label team=platform\n\n# Cluster operations\nCheck my ACP authentication\nList my ACP clusters\nSwitch to ACP cluster vteam-prod\nLogin to ACP cluster vteam-stage with token\n```\n\n### Trigger Keywords\n\nInclude 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.\n\n### Quick Reference\n\n| Task | Command Pattern |\n|------|----------------|\n| Check auth | `Use acp_whoami` |\n| List all | `List ACP sessions in PROJECT` |\n| Filter status | `List running sessions in PROJECT` |\n| Filter age | `List sessions older than 7d in PROJECT` |\n| Get details | `Get details for ACP session SESSION` |\n| Create | `Create ACP session with prompt \"...\"` |\n| Create from template | `Create ACP session from bugfix template` |\n| Restart | `Restart ACP session SESSION` |\n| Clone | `Clone ACP session SESSION as \"new-name\"` |\n| Update | `Update ACP session SESSION timeout to 1800` |\n| View logs | `Show logs for ACP session SESSION` |\n| View transcript | `Get transcript for ACP session SESSION` |\n| View metrics | `Show metrics for ACP session SESSION` |\n| Add labels | `Label ACP session SESSION with env=test` |\n| Remove labels | `Remove label env from ACP session SESSION` |\n| Filter by label | `List ACP sessions with label team=platform` |\n| Delete (dry) | `Delete SESSION in PROJECT (dry-run)` |\n| Delete (real) | `Delete SESSION in PROJECT` |\n| Bulk delete | `Delete session-1, session-2 in PROJECT` |\n| Bulk by label | `Stop sessions with label env=test` |\n| List clusters | `Use acp_list_clusters` |\n| Login | `Login to ACP cluster CLUSTER` |\n\n---\n\n## Tool Reference\n\nFor complete API specifications including input schemas, output formats, and behavior details, see [API_REFERENCE.md](API_REFERENCE.md).\n\n| Category | Tool | Description |\n|----------|------|-------------|\n| **Session** | `acp_list_sessions` | List/filter sessions |\n| | `acp_get_session` | Get session details |\n| | `acp_create_session` | Create session with prompt |\n| | `acp_create_session_from_template` | Create from template |\n| | `acp_delete_session` | Delete with dry-run support |\n| | `acp_restart_session` | Restart stopped session |\n| | `acp_clone_session` | Clone session configuration |\n| | `acp_update_session` | Update display name or timeout |\n| **Observability** | `acp_get_session_logs` | Retrieve container logs |\n| | `acp_get_session_transcript` | Get conversation history |\n| | `acp_get_session_metrics` | Get usage statistics |\n| **Labels** | `acp_label_resource` | Add labels to session |\n| | `acp_unlabel_resource` | Remove labels by key |\n| | `acp_list_sessions_by_label` | Filter sessions by labels |\n| | `acp_bulk_label_resources` | Bulk add labels (max 3) |\n| | `acp_bulk_unlabel_resources` | Bulk remove labels (max 3) |\n| **Bulk** | `acp_bulk_delete_sessions` | Delete multiple sessions (max 3) |\n| | `acp_bulk_stop_sessions` | Stop multiple sessions (max 3) |\n| | `acp_bulk_restart_sessions` | Restart multiple sessions (max 3) |\n| | `acp_bulk_delete_sessions_by_label` | Delete by label (max 3) |\n| | `acp_bulk_stop_sessions_by_label` | Stop by label (max 3) |\n| | `acp_bulk_restart_sessions_by_label` | Restart by label (max 3) |\n| **Cluster** | `acp_list_clusters` | List configured clusters |\n| | `acp_whoami` | Check authentication status |\n| | `acp_switch_cluster` | Switch cluster context |\n| | `acp_login` | Authenticate with Bearer token |\n\n---\n\n## Troubleshooting\n\n### \"No authentication token available\"\n\nYour token is not configured. Either:\n\n1. Add `token: your-token-here` to your cluster in `~/.config/acp/clusters.yaml`\n2. Set the `ACP_TOKEN` environment variable\n\n### \"HTTP 401: Unauthorized\"\n\nYour token is expired or invalid. Get a new token from the ACP platform administrator.\n\n### \"HTTP 403: Forbidden\"\n\nYou don't have permission for this operation. Contact your ACP platform administrator.\n\n### \"Direct Kubernetes API URLs (port 6443) are not supported\"\n\nYou're using a direct K8s API URL. Use the public-api gateway URL instead:\n\n- **Wrong**: `https://api.cluster.example.com:6443`\n- **Correct**: `https://public-api-ambient.apps.cluster.example.com`\n\n### \"mcp-acp: command not found\"\n\nAdd Python user bin to PATH:\n\n- **macOS**: `export PATH=\"$HOME/Library/Python/3.*/bin:$PATH\"`\n- **Linux**: `export PATH=\"$HOME/.local/bin:$PATH\"`\n\nThen restart your shell.\n\n### MCP Tools Not Showing in Claude\n\n1. Check Claude Desktop logs: Help → View Logs\n2. Verify config file syntax is valid JSON\n3. Make sure `mcp-acp` is in PATH\n4. Restart Claude Desktop completely (quit, not just close)\n\n### \"Permission denied\" on clusters.yaml\n\n```bash\nchmod 600 ~/.config/acp/clusters.yaml\nchmod 700 ~/.config/acp\n```\n\n---\n\n## Architecture\n\n- **MCP SDK** — Standard MCP protocol implementation (stdio transport)\n- **httpx** — Async HTTP REST client for the public-api gateway\n- **Pydantic** — Settings management and input validation\n- **Three-layer design** — Server (tool dispatch) → Client (HTTP + validation) → Formatters (output)\n\nSee [CLAUDE.md](CLAUDE.md#architecture-overview) for complete system design.\n\n---\n\n## Security\n\n- **Input Validation** — DNS-1123 format validation for all resource names\n- **Gateway URL Enforcement** — Direct K8s API URLs (port 6443) rejected\n- **Bearer Token Security** — Tokens filtered from logs, sourced from config or environment\n- **Resource Limits** — Bulk operations limited to 3 items with confirmation\n\nSee [SECURITY.md](SECURITY.md) for complete security documentation including threat model and best practices.\n\n---\n\n## Development\n\n```bash\n# One-time setup\nuv venv \u0026\u0026 uv pip install -e \".[dev]\"\n\n# Pre-commit workflow\nuv run ruff format . \u0026\u0026 uv run ruff check . \u0026\u0026 uv run pytest tests/\n\n# Run with coverage\nuv run pytest tests/ --cov=src/mcp_acp --cov-report=html\n\n# Build wheel\nuvx --from build pyproject-build --installer uv\n```\n\nSee [CLAUDE.md](CLAUDE.md#development-commands) for contributing guidelines.\n\n---\n\n## Roadmap\n\nCurrent implementation provides 26 tools. 3 tools remain planned:\n\n- Session export ([issue #28](https://github.com/ambient-code/mcp/issues/28))\n- Workflow management ([issue #29](https://github.com/ambient-code/mcp/issues/29))\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass (`uv run pytest tests/`)\n5. Ensure code quality checks pass (`uv run ruff format . \u0026\u0026 uv run ruff check .`)\n6. Submit a pull request\n\n---\n\n## Status\n\n**Code**: Production-Ready |\n**Tests**: All Passing |\n**Security**: Input validation, gateway enforcement, token security |\n**Tools**: 26 implemented ([3 more planned](https://github.com/ambient-code/mcp/issues/28))\n\n---\n\n## Documentation\n\n- **[API_REFERENCE.md](API_REFERENCE.md)** — Full API specifications for all 26 tools\n- **[SECURITY.md](SECURITY.md)** — Security features, threat model, and best practices\n- **[CLAUDE.md](CLAUDE.md)** — System architecture and development guide\n\n## License\n\nMIT License — See LICENSE file for details.\n\n## Support\n\nFor issues and feature requests, use the [GitHub issue tracker](https://github.com/ambient-code/mcp/issues).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambient-code%2Fmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fambient-code%2Fmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambient-code%2Fmcp/lists"}