MCP Connections

Purpose and Scope

MCP connections let an eve agent use a remote Model Context Protocol server that the application developer does not own or implement. The remote server publishes tools and schemas, while eve exposes the matching capabilities to the model through the built-in connection discovery flow. This is different from writing a local tool in the agent project: the source of truth for the tool list, input schemas, and remote behavior lives on the external MCP server. Use this page when you need to decide whether MCP is the right integration shape, create the connection file, choose authentication, and understand how the model will discover and call the resulting tools.

Sources: docs/connections/mcp.mdx, docs/connections/overview.mdx

Connections are part of eve’s filesystem-first authoring model. A connection file lives under the agent’s connections directory, and its filename becomes the runtime connection name. That convention matters because the model calls remote tools using a qualified name derived from both the connection name and the server-published tool name. For example, a file for Linear registers the connection as Linear in the project’s runtime namespace, and discovered tools are addressed with the connection name followed by the remote tool. The model does not receive the server URL or credentials; it searches descriptions and calls qualified tools through eve.

Sources: docs/connections/overview.mdx, docs/connections/mcp.mdx

Relevant Source Files

• docs/connections/mcp.mdx — Primary MCP connection guide, including when to use MCP, the defineMcpClientConnection example, transport requirements, Vercel Connect OAuth setup, user-scoped and app-scoped auth behavior, and static-token guidance.
• docs/connections/overview.mdx — Shared connections overview that defines the agent/connections/ convention, connection_search, qualified tool names, static-token behavior, app versus user credential ownership, and token privacy guarantees.
• docs/connections/openapi.mdx — Companion OpenAPI connection guide used to contrast MCP with OpenAPI and clarify when a provider-owned dynamic tool server is preferable to operation generation from an HTTP API contract.
• docs/connections/meta.json — Navigation metadata showing that the Connections section groups overview, MCP, and OpenAPI pages together.
• docs/agent-config.md — Runtime configuration reference for the root agent file; useful context because connections are project-level capabilities used alongside the agent model, limits, and durable workflow runtime settings.
• docs/channels/custom.mdx — Channel documentation that explains route auth, sessions, and event delivery; relevant because user-scoped connection auth depends on an active session with an authenticated principal, often established by a channel or route.

When to Choose MCP

Choose an MCP connection when the third-party service already exposes an MCP server, when the service should own its tool schemas dynamically, or when one connection should represent a family of related remote actions. The MCP server can evolve its available tools without requiring the eve project to model every operation as local TypeScript. This is a strong fit for products such as issue trackers, code hosts, warehouses, or internal platforms that already publish an MCP endpoint. The agent author writes a concise connection definition and focuses on describing the external capability in terms the model can use.

Sources: docs/connections/mcp.mdx

Choose an OpenAPI connection instead when the external service publishes an OpenAPI or Swagger document and you want eve to derive one tool per operation. OpenAPI generation is contract-driven: operation identifiers, paths, and schemas come from the API document. MCP is server-driven: the remote server publishes its own tools and schemas through the MCP protocol. That distinction should guide integration design. If the remote service has richer MCP semantics than its raw HTTP API, or if the server’s tool inventory is expected to change dynamically, MCP is the more natural fit.

Sources: docs/connections/mcp.mdx, docs/connections/openapi.mdx

Defining a Connection File

Create one module under the agent connections directory and export a default connection definition using the MCP helper. The filename is not just a local organization detail; it becomes the runtime connection name. A file named for Linear registers that connection name, and the model-visible tools are qualified under that namespace. The connection definition includes the remote MCP URL, a model-facing description, and an auth configuration. The URL must speak Streamable HTTP or Server-Sent Events, because eve connects to a remote MCP server rather than loading local tool code from the project.

Sources: docs/connections/mcp.mdx

import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
 
export default defineMcpClientConnection({
  url: "https://mcp.linear.app/mcp",
  description: "Linear workspace: issues, projects, cycles, and comments.",
  auth: connect("mcp.linear.app/linear"),
});

The description should be written for the model rather than for the developer reading the file. In eve’s connection model, discovery happens through the built-in connection search capability, and the description is a major signal for deciding whether to query a connection. A terse internal label is less useful than a concrete summary of the remote domain, such as the workspace objects and operations the server can help with. Treat this field like tool documentation: it should help the model decide when the connection is relevant, without exposing secrets or implementation details.

Sources: docs/connections/mcp.mdx, docs/connections/overview.mdx

Authentication Options

For OAuth-backed MCP servers, prefer Vercel Connect. Connect owns browser consent, encrypted token storage, refresh, and project access, while the helper from the Connect package plugs that lifecycle into eve’s connection auth. This design keeps credentials out of model context and conversation history. The setup flow is project-oriented: install the Connect package, link the Vercel project, create a connector for the provider, attach it, and pull environment variables. After that, the connection definition references the connector identifier rather than embedding a token or secret in source code.

Sources: docs/connections/mcp.mdx

npm install @vercel/connect
vercel link
vercel connect create mcp.linear.app --name linear
vercel connect attach <connector-uid> --yes
vercel env pull

By default, the Connect helper is user-scoped. That means the first tool call for a user may emit an authorization-required event with a URL, park the turn, and resume after the callback completes. User-scoped auth is not a generic prompt to find any human later; it requires the active eve session to already have a user principal from route auth or a platform channel. If there is no authenticated user on the session, the connection fails with a principal-required reason. Plan the surrounding route or channel auth before relying on per-user OAuth grants.

Sources: docs/connections/mcp.mdx, docs/connections/overview.mdx, docs/channels/custom.mdx

Use app-scoped auth when the MCP server should act as the agent itself instead of the signed-in user. In that configuration, eve asks Connect for one shared app token and the tool call does not require an interactive user consent flow at call time. This is appropriate for bot accounts, service installations, or shared workspace integrations. The tradeoff is operational: if the connector is missing or cannot issue an app token, the tool call fails terminally so an operator can fix the project setup rather than silently falling back to another credential.

Sources: docs/connections/mcp.mdx, docs/connections/overview.mdx

auth: connect({ connector: "mcp.linear.app/linear", principalType: "app" });

Static Tokens and Principal Scope

Use static-token auth when you already have a bearer token, API key, service account token, or an out-of-band OAuth process. The auth function returns a token result, and eve sends that token as a bearer authorization header on requests to the remote service. Because the token function runs on connection attempts, it can read from an environment variable, a secrets manager, an internal vault, or a custom token exchange. When a token has a known lifetime, returning an expiration timestamp allows eve to refresh ahead of time instead of waiting for a remote authorization failure.

Sources: docs/connections/overview.mdx, docs/connections/mcp.mdx

The principal type defines who owns the credential. With a token getter as the only auth configuration, app scope is the default, meaning one shared credential is keyed across sessions. Switch to user scope when each end user carries a separate token and the active session has an authenticated user principal. This choice is separate from the agent’s model settings in the root runtime configuration, but it affects runtime behavior during a turn. The model sees neither the token nor the URL; eve resolves and caches connection tokens per step while brokering the remote call.

Sources: docs/connections/overview.mdx, docs/agent-config.md

Runtime Flow and Edge Cases

At runtime, the model does not browse every remote endpoint directly. It uses connection search to find relevant external capabilities, then calls qualified tools exposed by the selected connection. That preserves a clean boundary: the agent author describes what the connection is for, eve brokers discovery and auth, and the remote MCP server owns the concrete tool schemas and execution. If the URL does not provide the expected remote transport, if the connector cannot issue a credential, or if user-scoped auth lacks a user principal, the connection cannot complete the call successfully.

Sources: docs/connections/mcp.mdx, docs/connections/overview.mdx

Custom channels and frontend routes often determine whether user-scoped auth can work. A custom channel can start or resume sessions, pass auth context, manage continuation tokens, and stream events back to the caller. That channel-level work is not an MCP connection itself, but it supplies the authenticated session context that user-owned connection credentials depend on. When designing an app with user OAuth, verify the channel or route establishes the user before the model reaches a connection tool. For app-scoped or static service credentials, this dependency is usually simpler because the credential is shared at the agent level.

Sources: docs/channels/custom.mdx, docs/connections/overview.mdx

Compact Reference

Next Steps

After adding an MCP connection, test it from the same route or channel context that production users will use, especially if the credential is user-scoped. Confirm that the connection description is specific enough for discovery, that the connector identifier is not confused with the runtime MCP endpoint, and that app versus user credential ownership matches the external system’s security model. For adjacent documentation, read the Connections overview for shared auth semantics, OpenAPI Connections for contract-generated HTTP integrations, Custom Channels for session auth and event delivery, and Agent Config for the runtime settings that govern the agent using these external capabilities.

Sources: docs/connections/meta.json, docs/connections/overview.mdx, docs/connections/openapi.mdx, docs/channels/custom.mdx, docs/agent-config.md