---
title: Connect a Warehouse (Optional)
description: Optional follow-up to the Build an Agent tutorial. Let each user connect their own warehouse over an OAuth MCP via Vercel Connect.
url: "https://eve.dev/docs/tutorial/connect-a-warehouse"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

A connection is an MCP server the model reaches through tools, with auth that eve drives for you. When you have a warehouse with an MCP server, connect it to the analytics assistant and let each user sign in through their browser. Complete [the tutorial with sample data](./first-agent) first.

[Vercel Connect](https://vercel.com/changelog/vercel-connect-secure-access-to-external-services-for-your-agents) is needed only for the OAuth integration on this page; the rest of the tutorial uses the [sample dataset](./query-sample-data).

## Before you start

- A warehouse account and a working MCP server for that warehouse, with its full endpoint URL. Connect manages credentials; it does not create a warehouse or turn a SQL database into an MCP server.
- Permission to authorize that server, with read-only access to the data you want the agent to query.
- A Vercel account and a linked project for Connect.
- An authenticated user on the eve session. Complete the route-auth setup in [Ship it](./ship-it#replace-placeholderauth) before trying per-user OAuth from a web app.

On a first pass through the tutorial, keep `run_sql` and [continue to Run analysis](./run-analysis).

## Register the connector

Run these commands from `analytics-assistant/`. Replace the example URL with your MCP server's actual endpoint, including its path:

```bash
npm install @vercel/connect
npx vercel@latest link
npx vercel@latest connect create "https://your-warehouse.example/mcp" --name warehouse
```

Follow the provider-specific registration prompts. Copy the **connector UID returned by the CLI**, not the display name `warehouse`. Attach the returned connector to this project, then pull the local environment:

```bash
npx vercel@latest connect attach "<returned-connector-uid>" --yes
npx vercel@latest env pull
```

`vercel env pull` provides `VERCEL_OIDC_TOKEN` for local requests to Connect. That token identifies your Vercel project, not an end user, so the steps below use the authenticated deployment from [Ship it](./ship-it#replace-placeholderauth). The [Connect reference](https://vercel.com/docs/connect) covers service-specific setup and project attachments.

## Declare the connection

Create `agent/connections/warehouse.ts`. Replace both the endpoint URL and connector UID below with the values you just configured:

```ts title="agent/connections/warehouse.ts"
import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";

export default defineMcpClientConnection({
  url: "https://your-warehouse.example/mcp",
  description: "The team's data warehouse: run read-only SQL and list tables and columns.",
  auth: connect("<returned-connector-uid>"),
});
```

The filename registers the eve connection as `"warehouse"`, independent of the connector UID, with tools named `warehouse__<tool>`. The remote server determines which tools exist; check its tool inventory and read-only permissions before using it.

By default, `connect("...")` uses a separate token for each user. Each user authorizes in their own browser, and eve gets that user's token before a tool call. The eve channel's route auth must map the signed-in app user to `principalType: "user"`. Sessions from `localDev()`, a runtime token, or a placeholder guard fail with `reason: "principal_required"` before OAuth starts. For a shared app credential, see [app vs. user auth](../connections#choose-app-vs-user-auth).

## Deploy and try it

Deploy the updated app so the authenticated web app includes the new connection:

```bash
npx vercel@latest deploy
```

Open the new HTTPS preview URL, sign in with the credentials configured in [Ship it](./ship-it#replace-placeholderauth), and create a new session. The local dev server uses `localDev()`, which doesn't provide the user identity this connection requires.

Ask the agent to inspect the warehouse's available tables, then query a table you have access to. Rely on the server's schema, not the tutorial's `orders` and `customers` tables.

If the user has not authorized the connector, the turn pauses and the channel shows a sign-in link. After the browser callback succeeds, the turn resumes and retries the tool call. Later calls reuse the grant while it remains valid. See [MCP connection troubleshooting](../connections/mcp#troubleshooting) if registration succeeds but the tool cannot connect.

## The token never reaches the model

Before each request to the MCP server, eve gets the user's token and sends it as `Authorization: Bearer <token>`. The model sees tool names, descriptions, and results. The token stays in your app's server code.

Gate the connection behind approval (`approval: once()`) or narrow which tools the model sees (`tools.allow`) when needed. See [MCP connections](../connections/mcp).

→ Return to the tutorial: [Run analysis](./run-analysis)

Learn more: [MCP connections](../connections/mcp) · [Authentication](../guides/auth-and-route-protection)

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)