Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs: Update Linear MCP URL and connections content (#360)

Allen Zhou7fd53f78e9c6
diff --git a/.changeset/linear-mcp-url.md b/.changeset/linear-mcp-url.md
new file mode 100644
index 000000000..fa7caa171
--- /dev/null
+++ b/.changeset/linear-mcp-url.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Update the curated Linear MCP connection to use Linear's Streamable HTTP endpoint at `https://mcp.linear.app/mcp`. The MCP and OpenAPI connection docs now include fuller setup guidance for Vercel Connect, static credentials, filters, and approvals.
diff --git a/docs/connections/mcp.mdx b/docs/connections/mcp.mdx
index 5b4624c32..45331a431 100644
--- a/docs/connections/mcp.mdx
+++ b/docs/connections/mcp.mdx
@@ -1,21 +1,71 @@
---
title: "MCP Connections"
-description: "Connect an eve agent to a remote MCP server and control which tools the model can discover."
+description: "Connect an eve agent to a remote MCP server, authorize it with Vercel Connect or static credentials, and control which tools the model can discover."
---
-MCP connections point eve at an MCP server you do not author. The server publishes its tools and schemas, and eve exposes matched tools to the model through `connection_search`.
+MCP connections point eve at a remote MCP server you do not author. The server publishes its tools and schemas, and eve exposes matching tools to the model through `connection_search`.
-Use MCP when the service already has an MCP server, when the server needs to own tool schemas dynamically, or when one connection should expose a family of related remote tools.
+Use MCP when the service already has an MCP server, when the server owns tool schemas dynamically, or when one connection should expose a family of related remote tools. Use an [OpenAPI connection](./openapi) instead when the service publishes an HTTP API contract and you want eve to generate one tool per operation.
## Define an MCP connection
-`defineMcpClientConnection` needs a `url` and a `description`:
+Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/linear.ts` registers as `linear`, and discovered tools are called as `linear__<tool>`.
```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
export default defineMcpClientConnection({
- url: "https://mcp.linear.app/sse",
+ url: "https://mcp.linear.app/mcp",
+ description: "Linear workspace: issues, projects, cycles, and comments.",
+ auth: connect("mcp.linear.app/linear"),
+});
+```
+
+The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself: it is the main signal `connection_search` uses when deciding which connection to query.
+
+## Use Vercel Connect for OAuth
+
+For OAuth-backed MCP servers, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns the browser consent flow, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so credentials never land in model context or conversation history.
+
+From the Vercel project or agent app that will run the connection:
+
+```bash
+npm install @vercel/connect
+vercel link
+vercel connect create mcp.linear.app --name linear
+vercel connect attach <connector-uid> --yes
+vercel env pull
+```
+
+Use the connector UID returned by the CLI in `connect("<connector-uid>")`. For Linear, the MCP runtime endpoint is `https://mcp.linear.app/mcp`, while the managed Connect service identifier is `mcp.linear.app`; those are related but not interchangeable.
+
+By default, `connect("...")` is user-scoped. The first tool call for a new user emits an `authorization.required` event with a URL to visit, parks the turn, and resumes after the callback completes. The active eve session must already have a user principal from route auth or from a platform channel. If there is no authenticated user, the connection fails with `reason: "principal_required"`.
+
+If the MCP server should act as the agent itself instead of the signed-in user, make the connector app-scoped:
+
+```ts title="agent/connections/linear.ts"
+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({ connector: "mcp.linear.app/linear", principalType: "app" }),
+});
+```
+
+App-scoped Connect auth is non-interactive. eve asks Connect for one shared app token; if the connector is missing or cannot issue an app token, the tool call fails terminally so an operator can fix setup.
+
+## Static tokens and headers
+
+Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
+
+```ts title="agent/connections/linear.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+ url: "https://mcp.linear.app/mcp",
description: "Linear workspace: issues, projects, cycles, and comments.",
auth: {
getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }),
@@ -23,39 +73,86 @@ export default defineMcpClientConnection({
});
```
-The `url` must speak Streamable HTTP or SSE. Write the `description` for the model, not for yourself. It shows up in `connection_search`, and the model uses it to decide which connection to query.
+Use `headers` for non-Bearer auth schemes or extra server configuration:
+
+```ts title="agent/connections/private-docs.ts"
+import { defineMcpClientConnection } from "eve/connections";
+
+export default defineMcpClientConnection({
+ url: "https://docs.example.com/mcp",
+ description: "Internal docs: search pages, owners, and recent changes.",
+ headers: {
+ "X-Api-Key": process.env.DOCS_API_KEY!,
+ },
+});
+```
+
+`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
+
+## No auth
+
+Omit `auth` and `headers` only for intentionally public or local-only servers:
+
+```ts title="agent/connections/local.ts"
+import { defineMcpClientConnection } from "eve/connections";
-The file path provides the connection name. `agent/connections/linear.ts` registers as `linear`, and remote tools appear as `linear__<tool>` after discovery.
+export default defineMcpClientConnection({
+ url: "http://localhost:3001/mcp",
+ description: "Local dev MCP server.",
+});
+```
+
+Do not use a no-auth connection for sensitive third-party services unless another layer protects the endpoint.
## Tool filters
-To narrow which remote tools the model sees, set exactly one of `tools.allow` or `tools.block`. Filtered-out tools do not appear in `connection_search`:
+MCP servers can expose broad read and write surfaces. Narrow what the model can discover with exactly one of `tools.allow` or `tools.block`:
```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
export default defineMcpClientConnection({
- url: "https://mcp.linear.app/sse",
- description: "Linear: read-only.",
- auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
+ url: "https://mcp.linear.app/mcp",
+ description: "Linear: read issue and project data.",
+ auth: connect("mcp.linear.app/linear"),
tools: { allow: ["search_issues", "get_issue"] },
});
```
-Use `allow` for the smallest safe surface, especially on MCP servers that expose write tools alongside read tools. Use `block` only when the server has a broad stable surface and you need to hide a few tools.
+Prefer `allow` for the smallest safe surface, especially when the server exposes write tools. Use `block` when the server has a broad stable surface and only a few tools should be hidden.
+
+## Approval gates
+
+For MCP tools that can create, modify, delete, message, transmit, purchase, or access sensitive data, add a human approval gate:
-## Auth, headers, and approval
+```ts title="agent/connections/linear.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineMcpClientConnection } from "eve/connections";
+import { once } from "eve/tools/approval";
+
+export default defineMcpClientConnection({
+ url: "https://mcp.linear.app/mcp",
+ description: "Linear workspace.",
+ auth: connect("mcp.linear.app/linear"),
+ approval: once(),
+});
+```
-MCP connections support the shared connection options:
+`once()` asks the first time in a session, `always()` asks on every tool call, and `never()` allows calls without approval. Authorization and approval work together: eve records approval before an OAuth park, then resumes without asking again for the same approved call.
-- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
-- `headers` for static or per-caller API-key schemes and extra server configuration.
-- `approval` for human-in-the-loop gates before connection tools run.
+## Troubleshooting
-See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.
+| Symptom | Check |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `principal_required` | A user-scoped `connect("...")` ran without an authenticated user. Return `principalType: "user"` from route auth, or use app-scoped auth. |
+| The model does not find the remote tool | Improve the connection `description`, then check `tools.allow` / `tools.block`. |
+| OAuth works locally but fails after deploy | Attach the Connect connector to the deployed Vercel project and verify the UID in `connect("...")`. |
+| The server rejects requests | Confirm the MCP URL, transport support, auth scheme, and any required headers. |
## What to read next
+- [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
- [OpenAPI connections](./openapi): generate tools from OpenAPI operations.
-- [Auth & route protection](../guides/auth-and-route-protection): the full interactive-OAuth flow with Vercel Connect.
+- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
- [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.
diff --git a/docs/connections/openapi.mdx b/docs/connections/openapi.mdx
index f4d528a80..073eb0d1c 100644
--- a/docs/connections/openapi.mdx
+++ b/docs/connections/openapi.mdx
@@ -1,13 +1,15 @@
---
title: "OpenAPI Connections"
-description: "Turn an OpenAPI 3.x document into eve connection tools, one tool per operation."
+description: "Turn an OpenAPI 3.x or Swagger 2.0 document into eve connection tools, authorize calls, and control which operations the model can discover."
---
-OpenAPI connections turn any OpenAPI 3.x document into connection tools, one per operation. Use OpenAPI when a service already publishes an HTTP API contract and you want eve to derive the model-facing tools from that contract.
+OpenAPI connections turn an OpenAPI 3.x or Swagger 2.0 document into connection tools, one per operation. Use OpenAPI when a service publishes an HTTP API contract and you want eve to derive model-facing tools from that contract.
+
+Use an [MCP connection](./mcp) instead when the service already exposes an MCP server, when the server should own tool schemas dynamically, or when the remote service has richer MCP semantics than its raw HTTP API.
## Define an OpenAPI connection
-`defineOpenAPIConnection` takes an HTTPS URL that eve fetches at runtime, or an inline parsed object:
+Create one file under `agent/connections/`. The filename becomes the runtime connection name, so `agent/connections/petstore.ts` registers as `petstore`, and generated operation tools are called as `petstore__<operation>`.
```ts title="agent/connections/petstore.ts"
import { defineOpenAPIConnection } from "eve/connections";
@@ -19,24 +21,120 @@ export default defineOpenAPIConnection({
});
```
-Each operation becomes `<connection>__<operationId>` (e.g. `petstore__getInventory`). When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead.
+Each operation becomes `<connection>__<operationId>`, for example `petstore__getInventory`. When an operation has no `operationId`, eve derives a deterministic `<method>_<sanitized-path>` name instead.
+
+`spec` can be an HTTPS URL that eve fetches at runtime, or an inline parsed OpenAPI object. Prefer a URL when the provider owns the contract and updates it; prefer an inline object for private APIs, generated specs you pin in source control, or small hand-authored contracts.
+
+## Base URL and servers
+
+eve resolves operation paths against `baseUrl` when you provide one. Otherwise, it derives the base URL from the spec:
+
+- OpenAPI 3.x: the first usable `servers` entry
+- Swagger 2.0: `schemes`, `host`, and `basePath`
+
+Use `baseUrl` when the spec is missing server data, points at the wrong environment, uses a relative server URL you do not want, or needs to be pinned for this agent.
+
+```ts title="agent/connections/crm.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+ spec: "https://api.example.com/openapi.json",
+ baseUrl: "https://api.example.com",
+ description: "CRM accounts, contacts, and opportunities.",
+});
+```
+
+## Use Vercel Connect for OAuth
+
+For OAuth-backed APIs, prefer [Vercel Connect](https://vercel.com/docs/connect). Connect owns browser consent, encrypted token storage, refresh, and project access. The `connect()` helper from `@vercel/connect/eve` plugs that lifecycle into eve's connection auth, so tokens never reach model context or conversation history.
+
+Create or attach a connector for the API provider from the Vercel project or agent app that will run the connection:
+
+```bash
+npm install @vercel/connect
+vercel link
+vercel connect create github --name github
+vercel connect attach <connector-uid> --yes
+vercel env pull
+```
+
+Then use the connector UID returned by the CLI:
+
+```ts title="agent/connections/github.ts"
+import { connect } from "@vercel/connect/eve";
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+ spec: "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
+ baseUrl: "https://api.github.com",
+ description: "GitHub repositories, issues, pull requests, and users.",
+ auth: connect("github/github"),
+});
+```
+
+By default, `connect("...")` is user-scoped. The active eve session must have a user principal from route auth or from a platform channel before the first operation call. If the API should act as the agent itself, make the connector app-scoped:
+
+```ts
+auth: connect({ connector: "github/github", principalType: "app" });
+```
+
+Use `tokenParams` on `connect(...)` when the provider requires explicit OAuth scopes, audiences, resource indicators, or authorization details.
+
+## Static tokens and headers
+
+Use `auth.getToken` when you already have a bearer token, API key, service account token, or out-of-band OAuth flow. eve sends the returned token as `Authorization: Bearer <token>`.
+
+```ts title="agent/connections/crm.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+ spec: "https://api.example.com/openapi.json",
+ baseUrl: "https://api.example.com",
+ description: "CRM accounts, contacts, and opportunities.",
+ auth: {
+ getToken: async () => ({ token: process.env.CRM_TOKEN! }),
+ },
+});
+```
+
+Use `headers` for non-Bearer auth schemes, version headers, or tenant routing:
+
+```ts title="agent/connections/notion.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+ spec: "https://developers.notion.com/openapi.json",
+ baseUrl: "https://api.notion.com",
+ description: "Notion pages, databases, comments, and users.",
+ headers: {
+ Authorization: `Bearer ${process.env.NOTION_API_KEY!}`,
+ "Notion-Version": "2022-06-28",
+ },
+});
+```
-The file path provides the connection name. `agent/connections/petstore.ts` registers as `petstore`, so operation tools are qualified under `petstore__`.
+`auth` and `headers` can also be functions that receive the active session context. Use that when credentials, tenants, or routing depend on the caller.
-## OpenAPI fields
+## Operation filters
-OpenAPI connections use the shared connection fields from [Connections](/docs/connections), plus two OpenAPI-specific fields:
+Most OpenAPI specs describe far more than the model should use. Narrow generated tools with exactly one of `operations.allow` or `operations.block`:
-| Field | Purpose |
-| ------------ | ------------------------------------------------------------------------------------------------------------- |
-| `baseUrl` | Base URL operation paths resolve against. Optional; defaults to the document's first usable `servers` entry. |
-| `operations` | Filter keyed on `operationId` (`allow` or `block`). Mirrors `tools` on MCP connections, but names operations. |
+```ts title="agent/connections/petstore.ts"
+import { defineOpenAPIConnection } from "eve/connections";
+
+export default defineOpenAPIConnection({
+ spec: "https://petstore3.swagger.io/api/v3/openapi.json",
+ description: "Pet store inventory and orders.",
+ auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
+ operations: { allow: ["getInventory", "placeOrder"] },
+});
+```
-Use `baseUrl` when the spec's `servers` list is absent, points at the wrong environment, or needs to be pinned for this agent.
+Filters match `operationId`. If an operation does not declare one, use the deterministic name eve derives from the method and path.
## Path parameters
-When an operation path contains dynamic segments, declare each segment as an OpenAPI path parameter. eve exposes path, query, header, and cookie parameters as top-level tool inputs, then substitutes `in: "path"` values into the matching `{name}` placeholder before making the request.
+When an operation path contains dynamic segments, the spec must declare matching OpenAPI path parameters. eve exposes path, query, header, and cookie parameters as top-level tool inputs, then substitutes `in: "path"` values into the matching `{name}` placeholder before making the request.
```ts title="agent/connections/cart.ts"
import { defineOpenAPIConnection } from "eve/connections";
@@ -48,12 +146,18 @@ export default defineOpenAPIConnection({
openapi: "3.0.3",
info: { title: "Cart API", version: "1.0.0" },
paths: {
- "/api/{dynamicsegment}/somethingelse": {
+ "/api/{cartId}/items/{itemId}": {
get: {
- operationId: "getSomethingElse",
+ operationId: "getCartItem",
parameters: [
{
- name: "dynamicsegment",
+ name: "cartId",
+ in: "path",
+ required: true,
+ schema: { type: "string" },
+ },
+ {
+ name: "itemId",
in: "path",
required: true,
schema: { type: "string" },
@@ -67,37 +171,30 @@ export default defineOpenAPIConnection({
});
```
-The parameter `name` must exactly match the placeholder inside the path. If the spec omits the `in: "path"` parameter, the generated tool has no input for that segment and eve cannot fill it in from query parameters.
+The parameter `name` must exactly match the placeholder inside the path. If the spec omits an `in: "path"` parameter, the generated tool has no input for that segment and eve cannot fill it in from query parameters.
-## Operation filters
+## Approval gates
-To narrow which generated tools the model sees, set exactly one of `operations.allow` or `operations.block`:
+Generated operation tools can mutate state just like authored tools. Add an approval gate when operations can create, modify, delete, message, transmit, purchase, or access sensitive data:
-```ts title="agent/connections/petstore.ts"
+```ts title="agent/connections/crm.ts"
import { defineOpenAPIConnection } from "eve/connections";
+import { once } from "eve/tools/approval";
export default defineOpenAPIConnection({
- spec: "https://petstore3.swagger.io/api/v3/openapi.json",
- description: "Pet store inventory and orders.",
- auth: { getToken: async () => ({ token: process.env.PETSTORE_TOKEN! }) },
- operations: { allow: ["getInventory", "placeOrder"] },
+ spec: "https://api.example.com/openapi.json",
+ baseUrl: "https://api.example.com",
+ description: "CRM accounts, contacts, and opportunities.",
+ auth: { getToken: async () => ({ token: process.env.CRM_TOKEN! }) },
+ approval: once(),
});
```
-Filters match `operationId`. If an operation does not declare one, use the deterministic name eve derives from the method and path.
-
-## Auth, headers, and approval
-
-OpenAPI connections support the shared connection options:
-
-- `auth` for static tokens, Vercel Connect, self-hosted interactive OAuth, or a per-caller provider resolver.
-- `headers` for static or per-caller API-key schemes and extra server configuration.
-- `approval` for human-in-the-loop gates before generated operation tools run.
-
-See [Connections](/docs/connections) for the shared auth, headers, and approval shapes.
+Combine `approval` with `operations.allow` for the smallest practical surface.
## What to read next
+- [Connections](../connections): shared auth, headers, approval, and per-caller patterns.
- [MCP connections](./mcp): connect to remote MCP servers.
-- [Auth & route protection](../guides/auth-and-route-protection): the full interactive-OAuth flow with Vercel Connect.
+- [Auth & route protection](../guides/auth-and-route-protection): route auth and the full interactive OAuth lifecycle.
- [Security model](../concepts/security-model): how connection credentials stay out of the model's reach.
diff --git a/docs/connections/overview.mdx b/docs/connections/overview.mdx
index 6c276c5d0..c18c40266 100644
--- a/docs/connections/overview.mdx
+++ b/docs/connections/overview.mdx
@@ -110,7 +110,7 @@ import { defineMcpClientConnection } from "eve/connections";
import { once } from "eve/tools/approval";
export default defineMcpClientConnection({
- url: "https://mcp.linear.app/sse",
+ url: "https://mcp.linear.app/mcp",
description: "Linear workspace.",
auth: { getToken: async () => ({ token: process.env.LINEAR_API_TOKEN! }) },
approval: once(),
@@ -130,7 +130,7 @@ import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
export default defineMcpClientConnection({
- url: "https://mcp.linear.app/sse",
+ url: "https://mcp.linear.app/mcp",
description: "Linear workspace: issues, projects, cycles, and comments.",
auth: connect("linear/myagent"),
});
@@ -147,7 +147,7 @@ import { connect } from "@vercel/connect/eve";
import { defineMcpClientConnection } from "eve/connections";
export default defineMcpClientConnection({
- url: "https://mcp.linear.app/sse",
+ url: "https://mcp.linear.app/mcp",
description: "Linear workspace: issues, projects, cycles, and comments.",
auth: connect({ connector: "linear/myagent", principalType: "app" }),
});
@@ -176,7 +176,7 @@ import {
} from "eve/connections";
export default defineMcpClientConnection({
- url: "https://mcp.linear.app/sse",
+ url: "https://mcp.linear.app/mcp",
description: "Linear workspace.",
auth: defineInteractiveAuthorization<{ verifier: string }>({
// Probed before every tool call. Return a token to run the tool;
diff --git a/packages/eve-catalog/src/index.ts b/packages/eve-catalog/src/index.ts
index 07682f226..1c51c74b7 100644
--- a/packages/eve-catalog/src/index.ts
+++ b/packages/eve-catalog/src/index.ts
@@ -151,7 +151,7 @@ export const INTEGRATIONS: readonly IntegrationEntry[] = [
surfaces: { scaffoldable: true, gallery: true },
connection: {
description: "Linear workspace: issues, projects, cycles, and comments.",
- mcp: { url: "https://mcp.linear.app/sse" },
+ mcp: { url: "https://mcp.linear.app/mcp" },
},
},
{
diff --git a/packages/eve/src/setup/scaffold/connections/catalog.test.ts b/packages/eve/src/setup/scaffold/connections/catalog.test.ts
index 2e08953f8..910a23ad5 100644
--- a/packages/eve/src/setup/scaffold/connections/catalog.test.ts
+++ b/packages/eve/src/setup/scaffold/connections/catalog.test.ts
@@ -95,7 +95,7 @@ describe("curated Connect services", () => {
describe("mcpServiceHost", () => {
test("extracts the host from a URL", () => {
- expect(mcpServiceHost("https://mcp.linear.app/sse")).toBe("mcp.linear.app");
+ expect(mcpServiceHost("https://mcp.linear.app/mcp")).toBe("mcp.linear.app");
});
test("returns undefined for missing or unparseable input", () => {