Connect a Warehouse
Purpose and Scope
This tutorial step moves the analytics assistant from a bundled sample dataset to a real warehouse connection. In eve terminology, a connection is the framework-managed bridge to an external system that the model can reach through tools while credentials remain outside the model context. The warehouse example uses a remote MCP server that exposes SQL-oriented capabilities, and eve is responsible for discovering those tools, mediating authentication, and resuming the agent turn after user authorization. This page explains the practical workflow, the naming conventions, and the safety boundaries a developer must understand before replacing sample data with production context.
Sources: docs/tutorial/connect-a-warehouse.mdx
The step is intentionally optional for readers without Vercel Connect access, because the tutorial source calls out that Vercel Connect is in private beta. If Connect is unavailable, developers can keep using the Step 3 sample dataset and still continue later tutorial steps. That fallback matters because the conceptual model is useful even when a real warehouse is not available: connection files live in a conventional filesystem location, connection names come from filenames, and remote tools appear under qualified names. The lesson is therefore both a task guide and a model for adding external context later.
Sources: docs/tutorial/connect-a-warehouse.mdx
Relevant Source Files
docs/tutorial/connect-a-warehouse.mdx- Defines the tutorial step, the warehouse connection example, the Vercel Connect setup flow, the user-facing authorization behavior, and the credential isolation guidance.
Core Primitives
The main primitive introduced here is the MCP connection. An MCP connection points eve at a server that already publishes tool schemas and handles the external service side of the integration. In the warehouse scenario, that server is a generic SQL MCP endpoint, and the description tells the model that it can run read-only SQL and inspect tables and columns. The model does not receive a database password, OAuth token, or endpoint secret in its prompt. Instead, it sees connection metadata and tool results, then asks eve to call qualified tools when those tools are relevant to the user question.
Sources: docs/tutorial/connect-a-warehouse.mdx
The second primitive is Vercel Connect authentication, imported through the @vercel/connect/eve helper. The tutorial uses Connect because each end user should authorize their own warehouse access through a browser flow, not share a single developer credential. The configured connector identifier links the eve connection to the Connect client that was registered for the project. By default, this OAuth mode is user scoped, so eve resolves the active user's token before each warehouse tool call and can refresh stored tokens without exposing them to the model.
Sources: docs/tutorial/connect-a-warehouse.mdx
The third primitive is the authenticated user principal on the eve channel route. A user-scoped connection can only launch the OAuth flow when the active session already represents a signed-in application user. The tutorial warns that if route protection still accepts only local development auth, a runtime token, or a placeholder guard, the first warehouse tool call fails with the principal-required reason instead of presenting a sign-in challenge. In practice, this means warehouse testing from a web application must be paired with route authorization that maps the signed-in app user to a user principal.
Sources: docs/tutorial/connect-a-warehouse.mdx
Declare the Connection
Create the warehouse connection under the agent filesystem. The filename is not incidental: placing the module at agent/connections/warehouse.ts registers the runtime connection name as warehouse. Remote tools surfaced from the MCP server are then qualified as warehouse__<tool>, which keeps external tool names unambiguous when an agent has several connections. This convention also makes the project easier to inspect because the runtime name, source file, and model-visible tool prefix all line up with the same developer-chosen term.
Sources: docs/tutorial/connect-a-warehouse.mdx
import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
export default defineMcpClientConnection({
url: "https://mcp.your-warehouse.example/sse",
description: "The team's data warehouse: run read-only SQL and list tables and columns.",
auth: connect("warehouse"),
});The declaration has three important pieces. The URL points at the remote MCP transport endpoint for the warehouse service. The description should be written as model-facing guidance, because it helps the agent decide when the connection is relevant and what kind of operations are appropriate. The auth field delegates OAuth to Vercel Connect using the connector UID chosen during Connect client registration. The tutorial names that UID warehouse, but in a real project the value should match the registered connector identifier rather than merely the local file name.
Sources: docs/tutorial/connect-a-warehouse.mdx
Setup Flow
Once Connect is enabled, the setup sequence is short but order sensitive. First install the Connect package in the agent project so the connect() helper is available. Then create a Connect client with the Vercel CLI, using the service type and the friendly name warehouse. After that, link the client to the project that will run the agent. Finally, run the project linking and environment pull commands so local development has the Vercel identity token needed to talk to Connect. Without that local environment, the code can compile while authorization fails at runtime.
Sources: docs/tutorial/connect-a-warehouse.mdx
npm install @vercel/connect
vercel connect create <type> --name warehouse
vercel link
vercel env pullThe tutorial also tells developers to link the client to the project, which may involve the connector attach or project association step appropriate to the Connect setup being used. The important operational idea is that the eve runtime, the Vercel project, and the Connect client must all refer to the same authorization configuration. A mismatch between the connector UID in source code, the registered Connect client, and the environment available locally will prevent the first tool call from obtaining the correct user token.
Sources: docs/tutorial/connect-a-warehouse.mdx
User Experience and Durable Resume
After the connection is declared, ask a question that genuinely needs warehouse data, such as how many enterprise customers signed up last month. On the first attempt, the model can select a warehouse tool, but eve discovers that no token exists for the current user. Instead of losing the in-progress turn, the channel shows a sign-in affordance and the turn parks at the authorization boundary. The user completes OAuth in the browser, the callback returns, and the agent resumes from that exact step so the query can continue.
Sources: docs/tutorial/connect-a-warehouse.mdx
That resume behavior is important for developer experience because the user does not need to repeat the question after signing in. It is also important for correctness because the model's plan and the pending tool call are preserved across the human authorization interruption. Later warehouse calls in the same session reuse the cached per-user token, so the user is not repeatedly prompted. The tutorial frames this as an example of durable parking from the earlier runtime step, applied here to an external context boundary rather than a simple local tool call.
Sources: docs/tutorial/connect-a-warehouse.mdx
Credential and Safety Boundaries
The tutorial is explicit that the token never reaches the model. Immediately before each MCP request, eve resolves the bearer credential and sends it as an authorization header to the remote server. The model receives tool names, descriptions, schemas, and results, but not the warehouse URL credentials or OAuth bearer. This separation is the reason connections are preferred over hand-rolled prompts that ask the model to manage secrets. The model can reason about available capabilities without ever becoming the component that stores or forwards the secret value.
Sources: docs/tutorial/connect-a-warehouse.mdx
For additional control, the tutorial points to two MCP connection levers: approvals and tool narrowing. An approval gate can require a human checkpoint before the connection is used, which is useful when warehouse queries are expensive, sensitive, or operationally risky. Tool filters can reduce the remote capability set so the model only sees the MCP tools that fit the agent's job. In a data assistant, that might mean exposing table listing and read-only query tools while withholding administrative or mutation-oriented operations if the server offers them.
Sources: docs/tutorial/connect-a-warehouse.mdx
Next Steps
After completing this step, continue to the analysis portion of the tutorial and keep the sample dataset fallback in mind if Connect access is not available. If you are integrating a production web application, verify route authorization before testing OAuth, because a missing user principal changes the first-run experience from a sign-in prompt to a terminal principal error. For deeper implementation work, read the MCP connections reference for transport, auth, approvals, and tool filters, then read the auth and route protection guide to make sure browser users are mapped into eve sessions correctly.
Sources: docs/tutorial/connect-a-warehouse.mdx