ACP (Agent Client Protocol): Integrating Coding Agents with the Vercel AI SDK

What ACP is, how it relates to MCP, how to integrate it into a TypeScript application, and what it means for teams building agent-powered developer tools.

1. What Is ACP, and What Problem Does It Solve?

When building AI-powered applications, the usual approach is to connect to a model provider, send a prompt, process the response, and optionally handle tool calls.

Coding agents introduce a different set of requirements.

Tools such as Claude Code, Gemini CLI, and Codex CLI can work with a codebase, inspect files, execute commands, make changes, and perform multi-step development tasks. Integrating these capabilities into our own applications requires more than simply displaying a model's text response.

Without a common protocol, each client may need a custom integration for every agent it wants to support. Agents may also need to implement different interfaces for different clients.

The Agent Client Protocol (ACP) addresses this problem by standardizing communication between coding agents and client applications. It was designed primarily for coding agents and code editors, including IDEs, but its architecture can also support other agent-enabled client interfaces.

ACP defines how a client and an agent communicate, establish sessions, exchange messages, report progress, and handle interactions such as permission requests.

The key point is that ACP is not an LLM or a model provider. It is a communication protocol for integrating agents into applications.

This distinction matters because a coding agent is more than a text-generation endpoint. It may have its own execution loop, tools, filesystem access, authentication requirements, and session lifecycle.

Reference: Agent Client Protocol — Introduction

2. ACP vs. MCP: What Is the Difference?

ACP and the Model Context Protocol (MCP) are complementary, not competing, technologies. They address different parts of an agent-based architecture.

• ACP (Agent Client Protocol) standardizes communication between an agent and its client.
• MCP (Model Context Protocol) standardizes how AI applications and agents interact with tools and external context sources.

Consider a developer platform that allows an agent to review a GitLab merge request, inspect the related code, make a correction, and run tests.

The responsibilities could be divided as follows:

1. ACP connects the application to the coding agent and carries the interaction.
2. MCP makes the required tools available to the agent, such as GitLab operations or access to other services.
3. The Vercel AI SDK provides application-level APIs for consuming agent output, including text generation and streaming through a familiar TypeScript interface.

A simplified architecture looks like this:

User
 |
 v
AI Application
 |
 v
Vercel AI SDK
 |
 v
ACP Provider
 |
 v
ACP-Compatible Agent
 |
 +----> Filesystem
 +----> Terminal / Tests
 +----> MCP Servers
           |
           +----> GitLab
           +----> Internal APIs
           +----> Other Services

This diagram illustrates a possible architecture, not a guarantee that every agent supports every capability shown. The available features depend on the agent, its ACP implementation, session configuration, and execution environment.

One important implementation detail is that the agent can connect to configured MCP servers directly. The application does not necessarily proxy every MCP request through itself.

This separation helps us design the system around clear responsibilities: ACP handles agent communication, MCP exposes tools, and the application owns the user experience and its policies.

References: ACP Architecture · MCP Documentation

3. What Does the ACP Provider in the Vercel AI SDK Offer?

The Vercel AI SDK has a community provider that integrates ACP-compatible agents through the LanguageModel interface.

The package is @mcpc-tech/acp-ai-provider.

It allows a TypeScript application to use an ACP-compatible agent through familiar AI SDK functions rather than implementing the underlying protocol integration from scratch.

Its documented capabilities include:

• Agent integration: Connect to supported agents such as Gemini CLI, Claude Code, and Codex CLI.
• Text generation: Use generateText to send a task and receive a result.
• Streaming: Consume output through streamText.
• MCP configuration: Configure MCP servers for the agent's session.
• Tool-call reporting: Expose provider-defined tool-call information through the AI SDK interface.
• Process management: Start agent processes and manage their lifecycle through the provider.

The important architectural nuance is that exposing an agent through the LanguageModel interface does not turn that agent into a conventional LLM API.

The provider offers a common application interface, but the underlying system may still execute multi-step workflows, use external tools, and manage its own state.

This abstraction is useful, but it does not make all agents behave identically.

Reference: AI SDK — ACP Community Provider

4. How to Integrate ACP

Step 1: Install the dependencies

For a Node.js and TypeScript project, install the AI SDK and the ACP provider:

pnpm add ai @mcpc-tech/acp-ai-provider

Installing the package is only the first step. The selected ACP agent must also be installed, configured, and authenticated according to its own requirements.

Step 2: Create an ACP provider

The following example uses Gemini CLI with its documented ACP command-line option.

import { createACPProvider } from '@mcpc-tech/acp-ai-provider';
import { generateText } from 'ai';

const provider = createACPProvider({
  command: 'gemini',
  args: ['--experimental-acp'],
  session: {
    cwd: process.cwd(),
    mcpServers: [],
  },
});

const { text } = await generateText({
  model: provider.languageModel(),
  prompt: 'Analyze this codebase and identify its main components.',
});

console.log(text);

Let's break down the configuration:

• command specifies the executable used to start the agent.
• args passes command-line arguments to that executable.
• cwd defines the working directory for the agent.
• mcpServers configures the MCP servers available to the session.
• provider.languageModel() exposes the configured agent through the AI SDK's model interface.

For example, setting cwd to a repository directory allows the agent to work in that context, subject to its capabilities and permissions.

The command-line arguments are agent-specific. The example assumes a compatible Gemini CLI version is installed and supports the documented ACP mode.

Step 3: Stream the response

For a long-running coding task, waiting for the entire response before displaying anything can produce a poor user experience.

The AI SDK provides streamText to consume output incrementally:

import { createACPProvider } from '@mcpc-tech/acp-ai-provider';
import { streamText } from 'ai';

const provider = createACPProvider({
  command: 'claude-code-acp',
  session: {
    cwd: process.cwd(),
    mcpServers: [],
  },
});

const { textStream } = streamText({
  model: provider.languageModel(),
  prompt: 'Review the error handling in this repository.',
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}

This pattern lets the application consume text as it becomes available.

However, text streaming and agent execution events are not the same thing. A coding interface may also need to display tool calls, file changes, permission requests, and execution progress.

Before building that experience, inspect the provider's supported event mapping and determine which events are exposed through the version you use.

Step 4: Provide MCP servers to the agent

ACP does not automatically grant an agent access to GitLab, a database, or another internal service. Those capabilities need to be configured and made available to the agent.

For example, the following configuration provides a filesystem MCP server restricted to /tmp:

const provider = createACPProvider({
  command: 'gemini',
  args: ['--experimental-acp'],
  session: {
    cwd: process.cwd(),
    mcpServers: [
      {
        type: 'stdio',
        name: 'filesystem',
        command: 'npx',
        args: [
          '-y',
          '@modelcontextprotocol/server-filesystem',
          '/tmp',
        ],
      },
    ],
  },
});

This follows the provider documentation's MCP configuration pattern. Verify the selected MCP server's current package, installation instructions, and compatibility before using it.

A few details are worth keeping in mind:

1. The agent must support the MCP configuration and transport being used.
2. Filesystem and other tool permissions should be restricted to the minimum required.
3. Providing an MCP server does not replace authentication, authorization, or execution isolation.

There is also a distinction between configuring MCP tools for the agent and exposing tool calls through the AI SDK.

The provider documentation shows passing provider.tools to AI SDK functions when tool-call information should be available through the SDK interface:

const result = await generateText({
  model: provider.languageModel(),
  prompt: 'List the files in the configured workspace.',
  tools: provider.tools,
});

Here, provider.tools refers to the provider-defined tools. It is not a replacement for configuring the MCP servers that supply capabilities to the agent.

This distinction becomes important when designing tool-call interfaces, logging agent activity, or building an interactive coding environment.

Reference: AI SDK — ACP Provider: Examples and Tool Usage

5. Advantages of Using ACP

Reuse existing coding agents

Building a capable coding agent from scratch involves much more than prompt engineering. It may require repository context management, file operations, command execution, tool orchestration, and recovery from failures.

Integrating an existing ACP-compatible agent can reduce the amount of infrastructure we need to implement ourselves.

This is especially useful when we want to experiment with coding workflows without immediately committing to maintaining our own full agent runtime.

Reduce client-agent integration overhead

ACP introduces a common communication interface for compatible clients and agents.

Instead of writing a completely different integration for every combination, an application can build against the protocol and add support for compatible agents.

There will still be agent-specific configuration and behavioral differences, but the common protocol can reduce duplicated integration work.

Build our own product experience

We do not necessarily have to expose developers to the agent's original terminal or editor interface.

We can build a custom interface in a web application, desktop client, or internal developer platform.

Possible features include:

• Task creation and tracking
• Streaming output and progress indicators
• Repository and session selection
• Permission-request dialogs
• Tool-call visibility
• File-change summaries
• Integration with existing code review workflows

These are application features built on top of the protocol, not turnkey features supplied by ACP itself.

Reuse MCP-based capabilities

Organizations that already maintain MCP servers may be able to reuse those integrations with compatible agents.

For example, an agent could use one set of configured tools to retrieve a merge request, another to read internal documentation, and another to run approved operations.

The benefit is architectural reuse: tools can be maintained as a separate capability layer rather than being embedded into every agent integration.

6. Limitations and Trade-offs

ACP simplifies communication, but it does not eliminate the complexity of operating coding agents.

The provider is community-maintained

The AI SDK ACP integration is a community provider, not a first-party Vercel model provider.

Being listed in the AI SDK documentation does not mean it has the same ownership, support commitments, or release lifecycle as a first-party package.

Before adopting it in production, evaluate maintenance activity, release compatibility, issue response, and the cost of maintaining a fallback or internal adapter.

Model selection is currently limited

The provider documentation states that it exposes a single language model representing the configured agent and does not currently support selecting a specific underlying model through its model interface.

This matters in environments where model choice is a platform-level concern.

For example, an organization might require specific models for latency, cost, data-handling, or compliance reasons. If model selection is controlled by the agent's own configuration, that control may not be available through the ACP provider itself.

The current limitations should be checked again before adoption because community provider features can change.

Process lifecycle and concurrency need attention

The documented provider runs in Node.js environments with child-process capabilities. Its documentation also notes that each language model instance spawns a new agent process.

That creates operational questions:

• When are agent processes started and terminated?
• How are timeouts and cancellations handled?
• What happens if an agent exits unexpectedly?
• Can sessions be resumed, and under what conditions?
• How are concurrent tasks isolated?
• What limits apply to CPU, memory, and execution time?

Creating a new agent process for every request without a lifecycle strategy can lead to unnecessary startup overhead, resource consumption, and operational instability.

For a production application, process management should be part of the design rather than an implementation detail left to chance.

ACP is not a sandbox

An agent may read files, execute commands, and invoke tools. ACP standardizes the communication involved, but the protocol alone does not isolate those operations.

The effective security boundary depends on the execution environment, the agent, its tool configuration, and the permissions granted to it.

A production implementation should consider:

• Isolated workspaces or containers
• Least-privilege filesystem and terminal access
• Explicit approval for sensitive operations
• Secure credential handling
• Auditable command and file-change records
• Resource limits and execution timeouts
• Cancellation and recovery behavior

The client should not assume that every agent implements the same permission model or supports the same capabilities.

Compatibility does not mean identical behavior

Two ACP-compatible agents can differ in supported features, authentication methods, tools, session handling, and their interpretation of a task.

ACP reduces communication-level coupling, but it does not guarantee identical results when switching agents.

Applications should define a common baseline of supported capabilities and make agent-specific differences explicit.

References: AI SDK — ACP Provider Limitations · ACP Protocol Overview · ACP Security Considerations

7. What Can an AI Chapter Lead Contribute?

The most valuable outcome is not simply introducing another protocol. It is using the protocol to establish a repeatable approach to agent integration, security, and developer experience across teams.

1. Establish a shared agent integration layer

Without a common approach, teams may implement their own agent lifecycle management, streaming, permission handling, and error recovery.

A shared integration layer can provide common abstractions for:

• Agent configuration and selection
• Session creation and cleanup
• Output streaming
• Cancellation and timeouts
• Permission handling
• Error reporting and retries
• Logging and observability

This allows feature teams to focus on their workflows instead of rebuilding the same integration infrastructure.

The abstraction should not hide meaningful differences between agents. It should provide a common baseline while allowing explicit capability checks and agent-specific configuration.

2. Define when to use ACP, MCP, or a model provider

A short architecture guide can help teams decide which technology belongs at which layer.

Requirement	Primary consideration
Generate text or structured output from a model	AI SDK model provider
Give an agent access to internal APIs or tools	MCP
Connect a coding agent to a client application	ACP
Stream task output and supported progress events	ACP integration and AI SDK
Enforce permissions and restrict execution	Application policies and runtime isolation

These are architectural guidelines, not mutually exclusive choices. A single system may use all three.

The objective is to avoid introducing a protocol simply because it is available. Every component should have a clear responsibility.

3. Define a secure execution standard

Coding agents introduce security concerns beyond those of a read-only chat interface.

Before teams use agents to make changes or run commands, establish standards for workspace isolation, tool permissions, credential management, user approvals, and auditability.

For instance, an agent that reviews a repository may only need read access. An agent that fixes a bug may require write access and permission to run tests. An agent that interacts with a shared environment should have a much stricter policy.

Permission decisions should be enforced by trusted application and runtime components rather than relying solely on an agent's instructions.

4. Run a measurable pilot

A working demo shows that an integration is possible. It does not show that the integration is useful or production-ready.

A good pilot would be a bounded merge request review and correction workflow:

1. The agent inspects a repository and identifies potential issues.
2. It explains the relevant files and findings.
3. It proposes a change or modifies permitted files.
4. It runs the available tests.
5. The application presents a summary of the changes and test results.
6. A developer reviews the result before it is merged.

The pilot should be compared with the existing workflow using the same tasks wherever possible.

Useful metrics include task completion rate, end-to-end duration, process startup overhead, tool-call failures, resource consumption, human intervention, and the number of changes accepted after review.

Security checks and regression tests should be treated as acceptance criteria, not optional improvements.

5. Create a reference implementation and share learnings

Instead of asking each team to interpret protocol documentation independently, provide a small reference application.

It should demonstrate provider configuration, MCP integration, streaming, process lifecycle management, permission handling, and failure scenarios.

Teams can then reuse the implementation and contribute improvements.

This approach makes the learning transferable: the organization develops an integration standard and a practical understanding of where the technology helps, where it introduces complexity, and which limitations still need work.

8. Questions to Answer Before Production Adoption

Before choosing ACP for a production workflow, I would evaluate the following:

• Does our selected agent implement ACP, and which version and capabilities does it support?
• Does the provider expose the events and controls required by our application?
• Where does the agent process run, and what resources can it access?
• How are credentials, permissions, and approval decisions managed?
• How are sessions, cancellation, timeouts, and process termination handled?
• How are concurrent users and tasks isolated?
• How will we measure reliability, cost, performance, and developer productivity?
• What is our plan if the community provider becomes incompatible with a new AI SDK release?

The key is to separate protocol compatibility from operational readiness.

A compatible agent may be easy to connect but still require substantial engineering around security, process management, observability, and user experience.

Conclusion

ACP is worth evaluating when we want to integrate coding agents into our own applications without building every agent-specific communication layer from scratch.

The Vercel AI SDK's community provider makes this approach accessible to TypeScript applications by exposing ACP-compatible agents through familiar APIs.

But ACP should not be treated as a universal replacement for model APIs or as an alternative to MCP. Its value is more specific: it standardizes communication between an agent and the client that uses it, while MCP can provide the tools an agent needs.

For an AI Chapter Lead, the opportunity is to turn that capability into a reusable engineering practice: define clear architectural boundaries, standardize secure integration patterns, run controlled pilots, and evaluate outcomes using measurable criteria.

My recommended starting point: choose one bounded coding workflow, build a small ACP-based reference implementation, and compare it with the existing approach. Make the production decision based on compatibility, operational effort, security, and measured results—not simply on whether the demo works.

---

References and Further Reading

1. AI SDK — ACP Community Provider — Installation, configuration, examples, tool usage, and documented limitations.
2. Agent Client Protocol — Introduction — ACP's purpose and the interoperability problem it addresses.
3. Agent Client Protocol — Architecture — Client-agent communication and MCP integration.
4. Agent Client Protocol — Protocol Overview — Sessions, messages, progress updates, and permission requests.
5. Agent Client Protocol — Security Considerations — Security boundaries and integration considerations.
6. Agent Client Protocol — TypeScript SDK — The TypeScript SDK for building ACP clients and agents.
7. Model Context Protocol Documentation — MCP concepts, tools, and integration patterns.
8. MCPC — GitHub Repository — The project associated with the ACP AI SDK provider.