[Feature Request] ZCode: Add Official ACP (Agent Client Protocol) Support for Third-Party Client Integration

Feature Request

Add official ACP (Agent Client Protocol) support to ZCode, enabling users to connect third-party ACP-compatible clients, editors, and harnesses directly to ZCode's agent capabilities without relying on unofficial workarounds or encountering CAPTCHA/blocking issues.

Target Audience:

• Users who want to use ZCode's GLM models through ACP-compatible tools
• Developers building custom agent clients that need ZCode integration
• Users seeking more open/flexible client options beyond the official ZCode desktop app

---

Background & User Request

Original Request:

"Does ZCode support ACP? I have been trying william0wang/zcode-acp from Github, but it keeps failing, and complains that it can't provide captcha. Isn't it supported to use an ACP client with ZCode. Your open models are nice. Please, make your model clients more open."

— خالد (Khaled), Discord

Problem Encountered:

User attempted to use third-party ACP bridge (william0wang/zcode-acp) but it fails because:

• Z.ai's web infrastructure uses anti-bot / Cloudflare security challenges
• Unofficial CLI scripts cannot render or solve CAPTCHA prompts
• Connection fails immediately at the authentication/challenge stage

---

Current State

Official Support Matrix:

Protocol	Status	Use Case
MCP (Model Context Protocol)	✅ Officially Supported	Adding tools/capabilities TO ZCode
API (OpenAI-compatible)	✅ Officially Supported	Using GLM models in third-party apps
ACP (Agent Client Protocol)	❌ Not Supported	Connecting external agents TO ZCode

Key Distinction:

• MCP: Allows ZCode to call EXTERNAL tools (outbound)
• ACP: Allows EXTERNAL agents to control ZCode (inbound)
• API: Allows using GLM MODELS elsewhere (model-only)

User wants: ACP — ability to use ZCode as a backend for external agent clients.

---

Why ACP Support Matters

1. Ecosystem Interoperability

ACP is emerging as a standard protocol for agent-to-agent communication. Supporting it would allow:

• ACP-compatible IDEs (Cursor, Windsurf, etc.) to use ZCode's agent capabilities
• Custom agent frameworks to leverage ZCode's tool integration
• Cross-platform agent orchestration

2. User Freedom & Choice

"Please, make your model clients more open."

— خالد

Users want flexibility in how they interact with Z.ai's models:

• Not locked into single ZCode desktop application
• Can choose preferred editor/IDE interface
• Build custom workflows combining multiple tools

3. Avoids Fragile Workarounds

Current situation forces users to:

• Rely on unofficial reverse-engineered projects (like zcode-acp)
• Battle CAPTCHA/security measures designed to block automation
• Deal with breaking changes when web endpoints update
• Risk account security by sharing session tokens with third-party tools

Official ACP support eliminates all of these issues.

4. Competitive Positioning

Platform	ACP Support	MCP Support	API Access
Claude/Cursor	✅ Yes	✅ Yes	✅ Yes
OpenAI Codex	✅ Yes	Partial	✅ Yes
ZCode/Z.ai	❌ No	✅ Yes	✅ Yes

Z.ai is behind on ACP support — this is a competitive gap.

---

Proposed Implementation

Option A: Native ACP Server in ZCode

Add an ACP server mode to ZCode that:

1. Listens on localhost (or configurable address) for ACP connections
2. Authenticates clients via API key or local token
3. Exposes ZCode capabilities as ACP-compliant resources/actions
4. Handles agent sessions through standard ACP message format

# Proposed ZCode configuration:
acp:
  enabled: true
  port: 13337  # Default ACP port
  auth: "api-key"  # or "local-token"
  allowed_clients:
    - "cursor-acp"
    - "custom-agent"
  capabilities:
    - file_read
    - file_write
    - terminal_execute
    - web_search
    - mcp_tools  # Expose MCP tools via ACP too

Option B: ACP Bridge / Proxy

Official Z.ai-maintained ACP proxy that:

1. Connects to ZCode via official APIs (not web scraping)
2. Translates ACP protocol ↔ ZCode internal protocol
3. Handles authentication properly (no CAPTCHA issues)
4. Distributed as official package (@zai/acp-bridge)

# Usage:
npx @zai/acp-bridge --api-key YOUR_KEY --port 13337
# Then connect any ACP client to localhost:13337

Option C: Hybrid Approach (Recommended)

1. Phase 1: Release official @zai/acp-bridge npm package (quick win)
2. Phase 2: Integrate ACP server natively into ZCode (full support)
3. Phase 3: Extend ACP to cover full ZCode feature set

---

Technical Considerations

Security Requirements:

Concern	Solution
Unauthorized access	API key authentication, rate limiting
Code execution safety	Sandbox ACP-initiated terminal commands
File system access	Configurable scope (project directory only)
Session isolation	Separate ACP sessions from GUI sessions

Compatibility:

• Must work with existing ACP client implementations
• Should follow ACP specification (once standardized)
• Fallback compatibility with MCP where protocols overlap

Performance:

• Localhost operation should add minimal latency
• Support streaming responses for real-time interaction
• Handle concurrent ACP connections

---

User Benefits

For Developers Like خالد:

Before (Current)	After (With ACP Support)
Unofficial tools that break	Official, maintained integration
CAPTCHA failures	Clean API-key authentication
Security risks from session sharing	Proper auth, scoped permissions
No support when things break	Official documentation + support

For Ecosystem:

• IDE vendors can integrate ZCode natively
• Agent framework authors can target Z.ai as backend
• Enterprise users can build custom workflows
• Open-source community can contribute ACP tooling

---

Addressing Potential Concerns

Q: "Doesn't API access solve this?"

A: Partially. API gives model access but NOT:

• ZCode's integrated tool chain (file ops, terminal, web search)
• Agent session management
• MCP tool integration through ACP
• ZCode-specific features (workspace, bindings, etc.)

ACP provides full agent capability, not just model access.

Q: "Isn't MCP enough?"

A: Different direction. MCP lets ZCode call OUT to tools.
ACP lets external agents call IN to ZCode.
They're complementary, not redundant.

Q: "Security risk of opening ZCode to external control?"

A: Mitigated by:

• Localhost-only by default (user opt-in for network)
• API key authentication
• Configurable permission scopes
• Audit logging of all ACP actions
• Rate limiting and session timeouts

---

Implementation Priority

Phase 1: Quick Win (2-4 weeks)

• Release official @zai/acp-bridge npm package
• Document setup process
• Basic ACP operations: chat, file read/write, terminal
• Authentication via existing API keys

Phase 2: Native Integration (1-2 months)

• Add ACP server to ZCode settings
• Built-in ACP endpoint (no separate process needed)
• Full capability mapping (all ZCode tools via ACP)
• GUI indicator showing active ACP connections

Phase 3: Advanced Features (2-3 months)

• Multi-client ACP sessions
• ACP → MCP bridging (expose MCP tools via ACP)
• ACP session recording/replay
• Enterprise features (SSO, audit logs, policy enforcement)

---

Alternative: Improve Third-Party Integration Docs

If full ACP support is too large for now:

1. Document supported integration points clearly
2. Provide official example code for common use cases
3. Create "ZCode Extension SDK" for safe plugin development
4. Publish stable internal API contracts that won't break
5. Offer "partner program" for tool builders with early access/support

This would help users like خالد build integrations without fighting security measures.

---

Additional Context

User's Perspective:

The request highlights a genuine user pain point:

• Z.ai has great open models that users want to use flexibly
• Current options feel restrictive compared to competitors
• Users are forced into unofficial workarounds that don't work well
• The ask is simple: "make your model clients more open"

Market Trend:

Agent protocols (ACP, MCP, A2A) are rapidly becoming standard.
Platforms that support multiple protocols will:

• Attract more developers
• Enable richer ecosystems
• Avoid lock-in complaints
• Stay competitive as agent tooling evolves

---

Discord Thread Reference

Original Request: https://discord.com/channels/1346756824233148527/1546742837792477235

Reporter: خالد (Khaled)

**Moderator Response Summary (Roman | Z):

• Confirmed ZCode does not officially support ACP currently
• Explained why third-party tools fail (CAPTCHA/security challenges)
• Directed user to API platform as current alternative
• Noted ZCode uses MCP (not ACP) for tool integration
• Committed to passing feedback to team about ACP support

---

Submitted by: Roman Galaxys10 (Roman) — Z.ai Volunteer Ambassador
Discord: bignavi_x
GitHub: romangalaxys10-spec
Source: Discord Community — User: خالد (Khaled)

Start by reviewing ZCode's existing MCP and OpenAI-compatible API integration points, then compare them with the ACP specification and the proposed native-server or bridge options. The issue does not name files, tests, or entry points. Done would require a decided scope, an authenticated ACP-compatible integration, and documentation covering supported capabilities.