---
title: MCP Channel
description: Publish an eve agent as an MCP server with auth support.
url: "https://eve.dev/docs/channels/mcp"
docs_index: /llms.txt
---

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

The MCP channel publishes your agent as an MCP server, so clients such as Claude Code can hand it long-running work. It lives in `agent/channels/mcp.ts`. Clients start and follow that work with four tools: `agent_start`, `agent_get`, `agent_update`, and `agent_cancel`. The channel can also [publish the agent's tools](#publish-the-agents-tools) for clients to call directly, and [its skills](#publish-the-agents-skills) for clients to read.

Use an [MCP connection](../connections/mcp) instead when your eve agent needs to call someone else's MCP server. To let agents that speak the Agent2Agent protocol delegate work instead, use the [A2A channel](./a2a).

## Configure the channel

Create `agent/channels/mcp.ts`. `auth` is required, even during development.

```ts title="agent/channels/mcp.ts"
import { localDev } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

export default mcpChannel({
  auth: localDev(), // required; replace before you deploy
});
```

`localDev()` accepts a stand-in local user under `eve dev` or `vercel dev`, and rejects every request in production. It checks the running environment, not the hostname, so an `eve start` production process rejects requests from localhost too. Replace it with one of the [production auth modes](#interactive-oauth) before you deploy.

### Routes

The Streamable HTTP endpoint serves `GET`, `POST`, and `DELETE` at `/eve/v1/mcp`. Set `route` to publish it elsewhere:

```ts title="agent/channels/mcp.ts"
import { localDev } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

export default mcpChannel({
  auth: localDev(),
  route: "/mcp",
});
```

## Invoke the agent

MCP clients receive four tools:

| Tool           | Input                         | Purpose                                                            |
| -------------- | ----------------------------- | ------------------------------------------------------------------ |
| `agent_start`  | `{ message }`                 | Start work and immediately return an invocation ID.                |
| `agent_get`    | `{ invocationId }`            | Read the invocation's complete current state.                      |
| `agent_update` | `{ invocationId, responses }` | Answer every open question or approval in the invocation together. |
| `agent_cancel` | `{ invocationId }`            | Ask unfinished work to stop.                                       |

`initialize` and `server/discover` also return `instructions` that describe these tools to the connecting model.

`agent_start` creates one eve session and returns once eve has saved the request. Keep its `invocationId`, and call `agent_get` until the invocation finishes. While the status is `working`, wait at least `pollAfterMs` between calls.

The invocation's `status` is one of:

| `status`                 | What to do                                                                                                                                                                                  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `working`                | Keep polling. The optional `statusMessage` says what the agent is doing, such as a running tool's [activity label](/docs/tools#label-tool-activity) or its name.                            |
| `input_required`         | Show each entry in `interactions`, keyed by `interactionId`. Send all the answers in one `agent_update`, one `{ interactionId, optionId?, text? }` per entry. It returns the current state. |
| `authorization_required` | Show each sign-in in `interactions`: its `signIn` URL, user code, or instructions. The invocation resumes on its own after the sign-in; keep polling.                                       |
| `completed`              | Read the optional `result`, the final assistant message. The turn and any [tasks](/docs/tools/workflows#run-calls-as-tasks-task) it started have finished.                                  |
| `failed`                 | Read the structured `error`.                                                                                                                                                                |
| `cancelled`              | The work stopped.                                                                                                                                                                           |

A tool result with `isError: true` means eve rejected the call, so fix the call. A `failed` status means the call succeeded and the work failed, so report it. Rejected calls carry `structuredContent.error` with a stable `code`, a short `message`, and `retryable`:

| `code`          | Meaning                                                                      | `retryable` |
| --------------- | ---------------------------------------------------------------------------- | ----------- |
| `invalid_input` | An argument was rejected, for example an oversized `message`.                | `false`     |
| `not_found`     | The invocation does not exist, has expired, or belongs to another caller.    | `false`     |
| `conflict`      | The invocation is not in the expected state; read it with `agent_get` first. | `true`      |
| `internal`      | eve failed; `errorId` correlates with server logs. No details are exposed.   | `false`     |

Limits: the MCP request body is 1 MiB, `message` 64 KiB, each response `text` 16 KiB (both in UTF-8 bytes), and one `agent_update` 64 responses. Oversized bodies get a JSON-RPC `413`, and oversized fields fail input validation before any work starts.

Tool arguments may contain at most 10,000 array elements and object members in total, including nested collections. Larger inputs return `isError: true` before the tool runs.

### Durability guarantees

- Once `agent_start` returns, the work survives restarts and redeploys. Only `agent_cancel` stops it. A dropped connection, client restart, or closed MCP session doesn't.
- `agent_start` isn't idempotent. If its response is lost, a second call starts a second invocation, so ask the user before you start again.
- `agent_update` answers one set of open requests. Re-sending accepted answers returns the current state. Different answers for a set that was already answered return `conflict`.
- `agent_cancel` asks the work to stop, so it can race with completion. Poll `agent_get` until the status is `cancelled`, `completed`, or `failed`, not only `cancelled`.

## Invocation ownership

Every MCP operation checks `auth` again. With an authenticated policy, an invocation belongs to the caller who started it, and knowing its ID isn't enough. Bearer tokens aren't stored with the invocation or forwarded to the agent's tools.

With `none()`, every caller is the same anonymous user, so the random invocation ID works like a password. Anyone who has it can read, answer, or cancel the invocation until workflow retention expires. Keep it out of logs and URLs. Responses include `expiresAt` when the workflow backend reports a retention deadline.

## Options

| Option              | Default                       | What it does                                                                        |
| ------------------- | ----------------------------- | ----------------------------------------------------------------------------------- |
| `auth`              | Required                      | One auth strategy or an ordered array. Use `none()` for public access.              |
| `route`             | `/eve/v1/mcp`                 | Path of the MCP endpoint.                                                           |
| `agent`             | `true`                        | Serves the `agent_*` tools and their instructions.                                  |
| `tools`             | `false`                       | Also [publishes the agent's tools](#publish-the-agents-tools).                      |
| `skills`            | `false`                       | Also [publishes the agent's skills](#publish-the-agents-skills).                    |
| `trustedForwarders` | Refuses the header with `403` | Lets a [router name the user](#forwarded-principals) that a published tool runs as. |
| `plainHttp`         | `"loopback"`                  | When a plain HTTP request is accepted; see [HTTP security](#http-security).         |

## Interactive OAuth

To have an MCP client open a sign-in flow, configure eve as an OAuth protected resource. Wrap the access-token verifier in `oauthResource()`:

```ts title="agent/channels/mcp.ts"
import { oauthResource, oidc } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

const issuer = "https://auth.example.com";
const resource = "https://agent.example.com/eve/v1/mcp";

const authenticateRequest = oidc({
  issuer,
  audiences: [resource],
});

export default mcpChannel({
  auth: oauthResource(authenticateRequest, {
    issuer,
    resource,
    scopes: ["agent:invoke"],
  }),
});
```

The `issuer` must issue tokens the wrapped verifier accepts. `scopes` tells clients what to request. The verifier still checks the signature, expiration, audience, and scopes.

`oauthResource()` adds protected-resource metadata to an `AuthFn`. `mcpChannel()` then publishes discovery and adds `resource_metadata` to Bearer challenges. eve doesn't run an authorization server: client registration, consent, token issuance, and authorization-server metadata belong to the identity provider.

Most hosted MCP clients, such as Claude, ChatGPT, and Grok, register themselves through Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) the first time a user connects. Choose an issuer that supports it, or pre-register each client. If registration fails, the client stops before it reaches eve.

### Verify the bearer token yourself

Use a custom `AuthFn` when token verification needs application-specific logic:

```ts title="agent/channels/mcp.ts"
import { extractBearerToken, oauthResource, verifyOidc } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

const issuer = "https://auth.example.com";
const resource = "https://agent.example.com/eve/v1/mcp";

async function verifyToken(request: Request) {
  const token = extractBearerToken(request.headers.get("authorization"));
  const result = await verifyOidc(token, {
    audiences: [resource],
    issuer,
  });

  return result.ok ? result.sessionAuth : null;
}

export default mcpChannel({
  auth: oauthResource(verifyToken, {
    issuer,
    resource,
    scopes: ["agent:invoke"],
  }),
});
```

`verifyOidc()` checks the token signature and claims against the issuer's discovery document. Return `sessionAuth` to accept the request; that caller then owns the invocation. Return `null` to pass to the next strategy. When no strategy accepts, eve returns `401`.

You can wrap any strategy in `oauthResource()`, including `vercelOidc()`, as long as the advertised authorization server issues tokens it accepts. `vercelOidc()` alone is Vercel workload identity and offers no interactive login.

### Protected-resource metadata

eve derives the metadata path from the full MCP resource identifier, per RFC 9728:

| MCP resource                           | Protected-resource metadata                                                 |
| -------------------------------------- | --------------------------------------------------------------------------- |
| `https://agent.example.com/eve/v1/mcp` | `https://agent.example.com/.well-known/oauth-protected-resource/eve/v1/mcp` |
| `https://agent.example.com/mcp`        | `https://agent.example.com/.well-known/oauth-protected-resource/mcp`        |

Set `resource` when the request doesn't show the public resource identifier, as behind a gateway or proxy that changes the origin or path. Set `metadataPath` to serve discovery at another path:

```ts
oauthResource(verifyToken, {
  issuer,
  metadataPath: "/.well-known/custom-resource",
  resource: "https://agent.example.com/eve/v1/mcp",
  scopes: ["agent:invoke"],
});
```

The metadata endpoint serves cross-origin `GET`, `HEAD`, and `OPTIONS` requests, so browser-hosted clients can find the authorization server.

## Other authentication modes

`mcpChannel()` accepts the same auth strategies as other eve channels: Basic auth, HMAC or ECDSA JWTs, generic OIDC, Vercel OIDC, and custom `AuthFn` policies. Pass one, or an ordered array. Without `oauthResource()`, they offer no interactive login, so configure credentials in the MCP client directly.

A request without accepted credentials gets a Bearer challenge. The challenge has `error="invalid_token"` when the request sent a Bearer token that every strategy rejected. For a verified caller without the needed scopes, throw `ForbiddenError` with an `error="insufficient_scope"` Bearer challenge. The channel keeps that challenge and adds the protected-resource metadata URL.

For how strategies are tried in order, see [Authentication](../guides/auth-and-route-protection).

### Public access

Use `none()` to expose the MCP endpoint without authentication:

```ts title="agent/channels/mcp.ts"
import { none } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

export default mcpChannel({
  auth: none(),
});
```

Anyone can then invoke the agent. See [Invocation ownership](#invocation-ownership) for what an invocation ID then allows. For a public demo, prefer [Interactive OAuth](#interactive-oauth) so each caller owns their invocations.

## HTTP security

The MCP endpoint checks each request before authentication:

- Remote endpoints require HTTPS. By default, HTTP is accepted only on loopback.
- `Host` must match the request URL.
- Browser protocol requests must have an exact same-origin `Origin`.

When eve runs behind a proxy, or serves callers on a private network, `plainHttp` accepts plain HTTP from more places:

| `plainHttp`         | Accepts plain HTTP                                                             |
| ------------------- | ------------------------------------------------------------------------------ |
| `"loopback"`        | Only from a loopback host, such as a local `eve dev`.                          |
| `"forwarded-https"` | Also when `X-Forwarded-Proto` is `https`, from a proxy that terminates TLS.    |
| `"allow"`           | From any host, for a network kept private some other way, such as one cluster. |

Any client can send `X-Forwarded-Proto`, so use `"forwarded-https"` only when every request passes through a proxy that sets it. eve reads the header's first value as the client's, so the outermost proxy must overwrite `X-Forwarded-Proto` and `X-Forwarded-Port`, not append to them. Under it, the OAuth metadata and challenges advertise the `https` URL the client used, on the port `X-Forwarded-Port` names when the proxy sends it. The `Host` and `Origin` checks apply under every setting.

Only the metadata endpoint allows cross-origin requests. For a browser application, put a same-origin backend or authenticated server-side proxy in front of the MCP endpoint.

The endpoint serves MCP `2026-07-28` and stateless `2025-11-25` Streamable HTTP, with no MCP transport session in either.

## Publish the agent's tools

Set `tools: true` to also publish every tool the agent can run outside a conversation. Set `agent: false` to stop serving the `agent_*` tools:

```ts title="agent/channels/mcp.ts"
import { localDev } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

export default mcpChannel({
  auth: localDev(),
  tools: true, // omit to serve only the agent_* tools
});
```

`tools/list` returns the `agent_*` tools first, then the agent's tools in name order with their input and output JSON schemas. eve doesn't publish these tools:

- framework tools, workflow tools, and provider tools;
- tools without `execute`;
- tools from dynamic resolvers or subagents; and
- while `agent` is on, an agent tool named like an `agent_*` tool. eve logs a warning.

With `agent: false`, the channel sends no `agent_*` instructions.

Each `tools/call` checks the arguments against the tool's input schema. It then runs the tool as the authenticated caller, or a [forwarded user](#forwarded-principals), with no model, turn, or workflow run. Every caller that the channel's `auth` accepts can call these tools, outside the agent's instructions, so review what becomes callable.

Unless the call joins a [tool session](#tool-sessions), it gets its own session:

- Authored state starts from its initial value, and updates aren't kept.
- A sandbox the tool opens is deleted when the call ends.
- Calls may run in parallel, and a call retried after a lost response runs again.

A tool that can't finish over MCP returns an error result with `isError: true` and a `structuredContent.error.code`:

| Code                     | When                                                                                             |
| ------------------------ | ------------------------------------------------------------------------------------------------ |
| `invalid_input`          | The tool rejected its input.                                                                     |
| `denied`                 | The tool's approval policy denied the call, or an anonymous caller sent a tool session key.      |
| `approval_required`      | The approval policy asks a person. The tool did not run; call it from a conversation instead.    |
| `authorization_required` | The tool needs a sign-in to a connection first. Sign in from a conversation, then call it again. |
| `internal`               | The tool failed. The message carries an error id that matches the server logs.                   |

### Trace context

MCP clients send W3C trace context in each request's `params._meta`. A valid `_meta.traceparent` becomes the parent of everything the request runs, including a published tool's `execute_tool` span. It takes precedence over a parent from the HTTP headers. A missing, malformed, or all-zero `traceparent` leaves the header parent in place. eve keeps `_meta.tracestate` only with a valid `traceparent`, and only up to 512 characters.

eve ignores `_meta.baggage`, so callers can't set trace audience, session lineage, or content capture. Those come from the channel and your `tracePolicy`. The `execute_tool` span records arguments and result only when that policy allows content capture, and never records exception text.

### Forwarded principals

A router can call the channel on behalf of its own users, such as another eve agent's [`forwardPrincipal` connection](../connections/mcp#forward-the-caller-to-an-eve-agent). It names the user in the `eve-forwarded-principal` header: unpadded base64url of UTF-8 JSON `{ current, initiator? }`, at most 16 KiB. eve accepts the header only when `trustedForwarders` is set, and only from an authenticated router that the predicate accepts:

```ts title="agent/channels/mcp.ts"
import { vercelOidc, vercelSubject } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

export default mcpChannel({
  auth: [vercelOidc()],
  tools: true,
  // Only the router deployment may name the user a tool runs as.
  trustedForwarders: (forwarder) =>
    forwarder.subject === vercelSubject({ teamSlug: "acme", projectName: "router" }),
});
```

The predicate receives the verified router and the users it names, as in the [eve channel](./eve)'s `trustedForwarders`. Match the router precisely; see [Accepting forwarded identity](../guides/auth-and-route-protection#accepting-forwarded-identity-from-another-deployment).

A published tool called with an accepted header runs as the forwarded user:

- `ctx.session.auth.current` is that user.
- `ctx.session.auth.initiator` is the named initiator, or that user.
- Both carry the router's `principalId` in the `eve:forwarded-by` attribute.

The `agent_*` tools act as the authenticated caller, not the forwarded user.

| Request                                                | Response                         |
| ------------------------------------------------------ | -------------------------------- |
| No header                                              | Runs as the authenticated caller |
| Malformed or over 16 KiB                               | `400`                            |
| The predicate refuses the router or the users it names | `403`                            |
| The router is anonymous (`none()`)                     | `403`                            |
| The channel has no `trustedForwarders`                 | `403`                            |
| The predicate throws                                   | `500`                            |

### Tool sessions

A tool session lets several `tools/call` requests share one sandbox, so a file one call writes is there for the next. With `tools: true`, `server/discover` advertises the `dev.eve/tool-sessions` extension in `capabilities.extensions`. To join a session, a client declares the extension in the request's `io.modelcontextprotocol/clientCapabilities`. It also sends a 1–512 character key in `_meta["dev.eve/tool-session"]`:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "write_note",
    "arguments": { "text": "Feed Biscuit at 18:00." },
    "_meta": {
      "dev.eve/tool-session": "alice-front-desk",
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": { "name": "front-desk", "version": "1.0.0" },
      "io.modelcontextprotocol/clientCapabilities": {
        "extensions": { "dev.eve/tool-sessions": {} }
      }
    }
  }
}
```

Calls share a session only when they have the same key and run as the same caller. That caller is the authenticated caller, or a [forwarded user](#forwarded-principals) together with the router that the channel's `auth` verified. Two forwarded users with one key, or one user forwarded by two routers, get separate sessions. eve ignores a key from a client that didn't declare the extension. Clients on the 2025-11-25 protocol send no per-request capabilities, so each call gets its own session.

Tool sessions need an authenticated caller. With `auth: none()`, the key alone would name the session, so anyone who knew it could read another client's sandbox. eve denies a keyed anonymous call with the `denied` code before anything runs. Unkeyed anonymous calls get a one-off session.

In a tool session:

- The sandbox opens on the first `ctx.getSandbox()`, and eve keeps it for later calls with the key. Concurrent first calls share one sandbox.
- A deploy that changes the sandbox definition (template, snapshot, open options in `sandbox.ts`, or resources) keeps the existing sandbox. The new definition applies only to a new sandbox, such as after expiry.
- Deployments that share a sandbox namespace, such as preview and production of one Vercel project, share the sandbox for the same caller and key.
- `ctx.session.id` is the same for every call with the key.
- Traces show each call as its own run, with a fresh `agent.run.id` and `gen_ai.conversation.id`, so traces don't link calls that share a key.
- Authored state starts from its initial value on every call, and updates aren't kept. Keep data that must outlive a call in the sandbox.
- Calls may run in parallel, in any order.

Tool sessions need Vercel Sandbox, just-bash, or a [custom provider](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls) that sets `toolSessions: true`. On another provider, a keyed call fails with `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` when the tool opens its sandbox. Tools that never open one still run.

On Vercel Sandbox, a tool-session sandbox's saved filesystem expires a day after its last use, whatever `snapshotExpiration` `sandbox.ts` sets. The next call with the key then gets a fresh, empty sandbox. If two calls find the expired filesystem at once, both can replace the sandbox, and the first one's files can be lost. Conversation sessions keep the authored `snapshotExpiration`.

just-bash keeps tool-session sandboxes on the local disk and never removes them. On Vercel Functions, a just-bash tool session lasts only as long as the function instance.

## Publish the agent's skills

Set `skills: true` to serve the agent's skills as [SEP-2640](https://modelcontextprotocol.io/seps/2640) skills under `skill://`. A client can then read the workflow knowledge behind the agent's tools:

```ts title="agent/channels/mcp.ts"
import { localDev } from "eve/channels/auth";
import { mcpChannel } from "eve/channels/mcp";

export default mcpChannel({
  auth: localDev(),
  skills: true,
  tools: true,
});
```

The channel declares the `io.modelcontextprotocol/skills` extension and serves the methods below. Every caller that the channel's `auth` accepts can read every served skill.

| Method                      | Returns                                                                                                                   |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `skills/list`, `skills/get` | Each skill's entry, `skill://<name>/SKILL.md`, with `resources` listing every file's `size` in bytes and `sha256:` digest |
| `resources/list`            | One resource per skill, its `SKILL.md`                                                                                    |
| `resources/directory/read`  | Every directory of a skill, including empty ones                                                                          |
| `resources/templates/list`  | Always empty                                                                                                              |
| `resources/read`            | UTF-8 text as `text`, anything else, such as images or Latin-1 files, as a base64 `blob`                                  |

Every skill and resource method carries the same private, 5-minute cache hint as `tools/list`. The `resources` capability declares `listChanged: false`, so clients re-read after the hint expires. A file removed after eve indexed the skill is an unknown resource (`-32602`).

eve serves a skill whole or not at all. It leaves out a skill, and logs a warning with the reason, when:

- Its `SKILL.md` frontmatter doesn't meet the Agent Skills format. The `name` must be up to 64 lowercase letters, digits, and single hyphens, and the `description` 1 to 1024 characters.
- It has more than 512 files or more than 16 MiB in total.
- Any of its files is over 512 KiB, unreadable, or has a path that can't be a `skill://` URI.

A `SKILL.md` whose frontmatter names the skill and has a `description` is served as written. Otherwise, eve serves it with generated frontmatter that carries the name and description, as for flat `.md` and module skills. The digest covers the served document. eve doesn't serve skills from dynamic resolvers or subagents.

Production builds embed skill files in the server bundle, so they count toward the deployed function's size.

## Troubleshooting

| What you see                                                                                    | What to do                                                                                                         |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `mcpChannel requires auth. Use none() for explicit public access.`                              | Set `auth`. Use `none()` only when the endpoint should be public.                                                  |
| `mcpChannel publishes nothing with agent, tools, and skills all false. Enable one.`             | Turn on at least one of `agent`, `tools`, or `skills`.                                                             |
| `Sandbox provider "<name>" cannot keep a sandbox between invokeTool calls` on a keyed tool call | Use Vercel Sandbox, just-bash, or a custom provider with `toolSessions: true` for [tool sessions](#tool-sessions). |

## What to read next

- [Authentication](../guides/auth-and-route-protection): configure inbound route authentication
- [MCP connections](../connections/mcp): let an eve agent call another MCP server
- [Sessions, runs & streaming](../concepts/sessions-runs-and-streaming): the sessions behind invocations

---

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)