MCP vs API for AI agents

MCP gives AI applications a standard way to discover and call tools. An API defines how software accesses a service, and an MCP tool often calls that API underneath. For an agent builder, the practical choice is whether to wrap the API directly in application code or connect through an MCP server.

Both approaches let a model request a tool call for application code to execute. Direct wrappers suit capabilities you already maintain in your backend. MCP suits tools shared across compatible clients and integrations with existing servers.

Key takeaways:

• Test which requests trigger each tool as well as whether its arguments are valid. Names, descriptions, and schemas all help the model select a tool.

• Expose only relevant tools to the model. Large catalogs may need filtering or deferred discovery to control context use.

• MCP standardizes tool discovery and invocation. Its 2026 request model removes protocol sessions but leaves application state to your storage layer.

• Direct API wrappers and MCP clients can both use typed schemas and automated tests. Choose based on the integration you need to maintain.

• Vercel can deploy an MCP endpoint beside your API routes in one project, with shared backend functions behind both.

Copy link to headingWhat are the key differences between MCP and APIs?

Both approaches can call the same backend service. Their differences are in discovery, the integration contract, and what your application maintains:

MCP gives callers a common protocol. Direct wrappers let your app use an API without that protocol layer; neither choice determines who owns the backend or whether it can be tested.

Copy link to headingWhere each tool is defined and deployed

An API-backed tool in your repository can call a service through its HTTP API or SDK and ship with your app. An MCP client connects to a server that may run as a local process, a remote service, or an endpoint in the same application. If another team maintains that server, its releases can change the tools your client discovers.

Copy link to headingHow each tool's inputs get checked

Tool arguments arrive at runtime on both paths and need validation. In the AI SDK, a tool's input schema also types its handler. Changing a parameter can expose incompatible handler code during compilation.

Automatic MCP discovery loads schemas at runtime. The AI SDK also lets you declare MCP tool schemas explicitly for typed inputs and outputs. Those local definitions still need integration checks against the remote server, whose implementation can change independently.

Copy link to headingWho writes the description the model reads

Your team writes descriptions for its own tools. MCP supplies descriptions from the server, which your client can adapt before presenting them to the model. Names, descriptions, and input schemas influence tool selection. Test prompts that should trigger each tool alongside prompts that should not; type checks cannot tell whether the model chose the right action.

Copy link to headingHow much context each set of tools uses

Every tool definition the model can see takes up part of its context window, so the difference is which tools reach it. With tools in your code, the model sees only the ones you pass. An MCP client that loads every tool a server lists spends that space before the model reads the request. Anthropic's tool search guidance recommends deferred loading at 10 or more tools or above 10,000 tokens of definitions.

Copy link to headingWhich apps can call each tool

Code editors, chat clients, and your own agent can share an MCP server when they support its transport and authorization flow. Direct wrappers can also be reused as library code, but an outside client needs an interface it knows how to call. MCP supplies that common interface.

Copy link to headingHow does MCP handle agent tool calls?

MCP uses JSON-RPC 2.0 to connect an AI application to tools and data. The application acts as the host and manages an MCP client for each server connection.

The host still controls model prompts and context management. MCP standardizes communication with tools; coordination between agents is a separate concern.

Copy link to headingHow MCP tool calls work

Self-contained tool calls follow the 2026-07-28 protocol:

• Transport: JSON-RPC messages travel over stdio for local servers or Streamable HTTP for remote servers.

• Discovery: Servers can expose prompts, resources, and tools. Clients use tools/list to discover available tools.

• Request metadata: Each request includes protocol and client information in its metadata. It replaces the initialization handshake and session header.

• Version discovery: Servers must support server/discover. Clients may query it or handle an unsupported-version error directly.

• Invocation: The host decides which tool definitions to give the model. Its client sends tools/call with the selected name and arguments.

Earlier deployments that kept protocol sessions in memory could need sticky routing or shared session storage. Removing those sessions simplifies request routing, but databases, background jobs, and other application state still need storage that the serving instance can access.

Copy link to headingAdvantages and limitations of MCP

MCP gives different hosts a shared integration contract. Your application still decides which servers and tools it trusts:

• Shared interface: One server can serve multiple compatible clients without an integration written specifically for each host.

• Authorization-aware discovery: Servers may vary the tool list by the caller's credentials. They must still enforce permissions when tools run.

• Cache hints: Complete tool-list results include freshness and cache-scope hints. These guide reuse without guaranteeing that the list stays unchanged.

• User consent: Hosts are responsible for presenting tools and obtaining consent. The protocol cannot enforce the quality of their approval flows.

Connecting a server also introduces inputs and behavior to review:

• Descriptions and results: Untrusted text can influence the model before or after a tool call. Limit the tools exposed and review their instructions.

• Annotations: Read-only or destructive-action labels are not proof of behavior. Treat annotations as untrusted unless you trust their source.

• Execution: Tools run code with the server's authority. Check which systems each tool can access and what changes it can make.

• Definition changes: Upstream names, schemas, and descriptions can change. Local definitions control what reaches the model. The server implementation can still change independently.

• Protocol maintenance: Roots, Sampling, and Logging were deprecated in July 2026. Their earliest possible removal is a revision on or after July 28, 2027; the specification does not impose that date as a migration deadline.

Every third-party MCP server deserves the scrutiny of untrusted input, so vet it before connecting and keep side-effecting tools behind an approval step.

Copy link to headingCommon MCP use cases

AI clients you don't control are where MCP earns its place, since your tools have to work inside apps you can't modify. These cases fit the pattern:

Copy link to headingCoding agents and IDEs

Publishing an MCP server lets supported code editors connect without an editor-specific integration. Developers configure the server, complete its authorization flow, and approve the tools their agent may use. Availability depends on the editor's supported MCP features and workspace settings.

Copy link to headingProducts exposed to outside AI clients

When ChatGPT, Claude, or other outside clients need your product, you can't add tools inside their apps. Gating an MCP server with OAuth lets each person grant access to their own account.

Copy link to headingApp introspection during development

Next.js 16 and later expose an MCP endpoint at /_next/mcp during development by default. The next-devtools-mcp integration connects agents to the running app's errors, routes, logs, and compilation information without a custom API.

Copy link to headingHow do API-backed tools work?

An API exposes a service through HTTP, gRPC, or another interface. Your agent can use it through a tool handler that manages requests, credentials, and retries. The service contract may be documented in OpenAPI, defined in protocol buffers, or exposed through a typed SDK.

Copy link to headingHow API-backed tool calls work

An API-backed tool gives the model a name, description, and input schema. The model requests a call with arguments; application code performs the operation.

In the AI SDK, tool() defines that contract. An optional execute function can call the API directly. Applications can also handle tool calls elsewhere, such as in a client or queue consumer.

With stopWhen configured, the SDK can pass tool results back to the model for another generation. The loop ends when there are no further tool calls or the configured stopping condition is met.

Copy link to headingAdvantages and limitations of API-backed tools

Direct wrappers let you define tools around the API operations your app needs:

• Argument schemas: Strict tool calling can constrain arguments to a schema on supported providers. Business rules and permissions still need handler checks.

• Descriptions: Your application controls the names and instructions presented to the model, including definitions selected or generated for a particular request.

• Execution: Handlers can call service SDKs or APIs without an MCP client/server exchange. They can also forward work to another process.

• Tests: Unit tests can exercise the handler with mocked dependencies. Integration tests check the real API contract and failure behavior.

The maintenance work sits with your application. Each service needs authentication, error handling, and a tool contract suited to the agent's task. You must also decide how new capabilities enter the available tool set and how contract changes reach other applications that reuse the code.

Tools with side effects need idempotent handlers before an agent retries them, because a repeated call can duplicate an order or a payment on either path.

Copy link to headingCommon API-backed tool use cases

One app owning both the capability and its contract is where API-backed tools earn their place. These cases follow from it:

Copy link to headingFixed backend workflows

An order lookup or report export has a small set of inputs that maps well to a typed schema. Define the tool around those inputs and let its handler call the service directly. Runtime validation checks the arguments sent by the model; the handler then applies the service's access rules.

Copy link to headingInternal services with generated clients

An OpenAPI definition can generate typed clients, server scaffolding, and test tooling. gRPC compiler plugins generate code from protocol buffer definitions. Your tool handler can call the generated client.

Copy link to headingTools that hold sensitive credentials

Refunds and account changes need credentials that should stay outside the model context. With a direct wrapper, your handler reads the credential from the server environment and calls the API. An MCP server can protect credentials in the same way, but a third-party server introduces another party whose access and credential handling you need to assess.

Copy link to headingMCP or API? How to choose for your agent

Start with the integration you already have. Direct tools are a straightforward fit for backend functions your application owns. An existing MCP server may avoid rebuilding a service integration, and publishing one can make your own tools available to other clients.

Mixed answers are normal. One agent can call tools defined in its own code and tools from a shared MCP server in the same loop.

Task-oriented tools can reduce the number of calls an agent must coordinate. For example, deploy_project can handle project creation, environment configuration, deployment, and domain setup behind one interface. That tool still needs clear approval and retry behavior for each action it performs.

Copy link to headingHow Vercel runs MCP servers alongside your APIs

Your API routes and MCP endpoint can share a Vercel project and backend functions. Exposing MCP then needs no separately managed server.

With the AI SDK's MCP client, you choose which tools from compatible servers to expose alongside tools defined in your code.

Copy link to headingMCP endpoints inside existing API routes

mcp-handler turns an MCP server definition into a Web-standard HTTP handler for Next.js, Nuxt, SvelteKit, and other Request/Response frameworks. Its 2.x release supports the 2026 protocol and stateless compatibility with 2025-era Streamable HTTP clients without Redis.

The route below uses Node.js 20+, mcp-handler 2.x, the MCP server SDK 2.x, and Zod 4. It assumes your app supplies two helpers: token verification that returns the caller's user ID, and an order lookup that enforces access for that user.

import type { AuthInfo } from "@modelcontextprotocol/server";
import { createMcpHandler, withMcpAuth } from "mcp-handler";
import { z } from "zod";
import { verifyAccessToken } from "@/lib/auth";
import { getOrderStatus } from "@/lib/orders";

const handler = createMcpHandler((server) => {
  server.registerTool(
    "get_order_status",
    {
      description: "Look up the status of one of the caller's orders by its ID",
      inputSchema: z.object({ orderId: z.string() }),
    },
    async ({ orderId }, ctx) => {
      const userId = ctx.http?.authInfo?.extra?.userId;
      if (typeof userId !== "string") throw new Error("Unauthorized");
      const status = await getOrderStatus(orderId, userId);
      return { content: [{ type: "text", text: status }] };
    },
  );
});

// Returns AuthInfo for a valid token from your auth provider, or undefined
const verifyToken = async (
  req: Request,
  bearerToken?: string,
): Promise<AuthInfo | undefined> => {
  if (!bearerToken) return undefined;
  return verifyAccessToken(bearerToken);
};

const authHandler = withMcpAuth(handler, verifyToken, { required: true });

export { authHandler as GET, authHandler as POST };

The wrapper returns a 401 challenge when token verification fails. Your verifier must validate tokens for this server and provide the caller's user ID. The order helper must enforce ownership before returning a status.

For OAuth clients, also configure the protected-resource metadata and authorization server. The same authorized order lookup can back a direct AI SDK tool, allowing both interfaces to share one implementation.

Copy link to headingBursty tool traffic on Fluid compute

MCP traffic can be idle between tasks and burst when an agent starts work. Capacity reserved for those bursts may sit unused between calls.

Fluid compute runs multiple invocations on one instance, reuses idle capacity before allocating new instances, and scales dynamically. The transport choice also changes CPU cost. One MCP server on Vercel cut CPU consumption by more than 50% after moving to Streamable HTTP. With Active CPU pricing, CPU charges accrue only while code is actively running.

Copy link to headingLong-running tools on Vercel Functions and Sandbox

Some tools do work that outlasts a single request, such as running a large analytics query or rebuilding a search index. If the function times out, the agent receives an error instead of a result.

Fluid compute limits functions to 300 seconds on Hobby and 800 on Pro or Enterprise. The extended duration beta allows 1,800 seconds on Pro and Enterprise for supported Node.js, Bun, and Python runtimes.

Configure the extension per function with maxDuration. BYOC remains limited to 800 seconds during beta.

Tools can start a detached command in Vercel Sandbox and return an ID for polling. On Pro and Enterprise, sessions can run for up to 24 hours.

Copy link to headingPinned definitions for third-party tools

An agent that passed review last week can behave differently this week if a server it depends on rewrites a description.

mcp-to-ai-sdk generates static AI SDK tool definitions from a compatible MCP server. The schemas and descriptions live in your codebase, where you can edit them or review changes during regeneration. Newly added server tools are not automatically exposed to the model.

Generated tools still call the original server. Local definitions do not pin its implementation or results, and upstream contract changes can break calls. Keep integration checks alongside review of the generated definitions.

Copy link to headingPlatform context through Vercel MCP

Debugging a deployment requires current logs and settings. Vercel MCP lets agents search documentation, inspect logs, and manage projects or deployments.

OAuth connections are available on all plans under Vercel's AI Product Terms. Tools depend on server configuration, the OAuth grant, and team permissions. Enable human confirmation before changing projects or deployments.

Copy link to headingShare one backend capability through MCP

Choose a backend function with a clear input contract and permission check, such as the order lookup above. Expose it through an MCP route and test that the direct call and MCP call return the same authorized result.

Add the route to your existing Vercel app, start a new project, or use an MCP server from the template gallery.

Copy link to headingFrequently asked questions about MCP vs API

Copy link to headingWill MCP replace APIs?

No. MCP standardizes how AI applications discover and call tools. Those tools can use existing APIs, databases, or other services. An order-status tool, for example, can call the same API your application already uses without replacing that API.

Copy link to headingIs MCP like an API gateway?

MCP standardizes tool discovery and invocation. An API gateway handles routing, authentication, and rate limits for backend services. Tool handlers still need to validate inputs and authorize operations.

Vercel AI Gateway routes model requests to providers.

Copy link to headingHow do you convert an API to MCP?

Tools such as FastMCP can generate an MCP server from an OpenAPI definition. Configure authentication for the underlying API, expose the operations your users need, and test their inputs and results. Combine related endpoints when that avoids repeated coordination by the agent.