MCP door: expose Vendo tools to Claude, ChatGPT, Cursor

​

When to use it

• You want an installable MCP server that exposes your product’s tools to third-party agents.
• Users of those agents should act as themselves in your product, with the same policy and approvals you enforce in-product.
• You already own a session and consent flow you can plug in behind an OAuth seam.

​

Enable the door

// lib/vendo.ts
import { createVendo } from "@vendoai/vendo/server";
import type { HostOAuthAdapter } from "@vendoai/vendo";

const oauth: HostOAuthAdapter = {
  async session(request, { returnTo }) {
    // Return the current host subject, or redirect the browser to login.
    // Send the user back through `returnTo` so the door resumes the exact
    // authorization request without a login → authorize → login loop.
    const user = await resolveSession(request);
    if (user) return { subject: user.id };

    const login = new URL("/login", request.url);
    login.searchParams.set("returnTo", returnTo);
    return Response.redirect(login);
  },
  async principal(subject) {
    // Re-resolved on every bearer-authenticated MCP request. Return null to revoke.
    const user = await lookupUser(subject);
    return user ? { kind: "user", subject: user.id, display: user.name } : null;
  },
};

export const vendo = createVendo({
  model,
  principal: resolvePrincipal,
  mcp: true,
  oauth,
});

// app/api/vendo/[...vendo]/route.ts
import { nextVendoHandler } from "@vendoai/vendo/server";
import { vendo } from "@/lib/vendo";

export const { GET, POST, DELETE } = nextVendoHandler(vendo);

​

Consent page

​

Theme it

​

Replace the page

const oauth: HostOAuthAdapter = {
  async session(request, { returnTo }) {
    /* as above */
  },
  async authorize(request, { clientName, scopes, consent }) {
    // `consent` is present because `session` is defined. Render your own page
    // and post the door's form values back to `consent.action`.
    return new Response(renderConsent({ clientName, scopes, consent }), {
      headers: { "content-type": "text/html; charset=utf-8" },
    });
  },
  async principal(subject) {
    /* as above */
  },
};

​

Route the discovery paths

// app/.well-known/[...vendo]/route.ts
import { vendo } from "@/lib/vendo";

export const GET = (request: Request) => vendo.handler(request);

• /.well-known/oauth-protected-resource/api/vendo/mcp (RFC 9728 protected-resource metadata)
• /.well-known/oauth-authorization-server/api/vendo/mcp (RFC 8414 authorization-server metadata)
• /.well-known/mcp/server-card.json (server card; /.well-known/mcp-server-card is an alias)

app.use("/api/vendo", mountVendo());
app.use("/.well-known", mountVendo());

​

Set VENDO_BASE_URL

• Discovery and audience binding. Behind a reverse proxy (Railway, Fly, any TLS terminator), the request reaching your process carries the proxy-internal origin. The door derives its OAuth discovery documents (issuer, endpoint URLs, the protected-resource resource) and its token audience binding from VENDO_BASE_URL when set, so clients see your public origin instead of an unreachable internal one. Forwarded headers such as X-Forwarded-Host are never trusted. Without it, the door falls back to the request URL, which is fine for local development and wrong behind a proxy.
• Route-binding base. Host tools that bind to routes need a base origin. The wire normally learns its own origin from the first in-product request, but door requests never teach it (only wire routes do); VENDO_BASE_URL gives door-first traffic a base to resolve host routes against.

VENDO_BASE_URL=https://app.example.com

​

Configure the door through the umbrella

export const vendo = createVendo({
  model,
  principal: resolvePrincipal,
  oauth,
  mcp: {
    baseUrl: "https://app.example.com",
    remoteAs: {
      issuer: "https://auth.example.com",
      audience: "https://app.example.com/api/vendo/mcp",
    },
    federation: { secret: process.env.VENDO_MCP_FEDERATION_SECRET! },
  },
});

​

How door calls reach host tools

• On successful OAuth, the door records the user’s consent for that client.
• When a door tool call resolves to a host route, Vendo calls actAs(principal, grant) to source auth material for the OAuth’d user.
• Without a real grant or a consent record, the call fails closed.
• Without actAs configured, the tool returns a not-implemented error, the same clean degradation as an away automation.

​

Delegate to an external authorization server

export const vendo = createVendo({
  model,
  principal: resolvePrincipal,
  mcp: true,
  oauth,
  remoteAs: {
    issuer: "https://auth.example.com",
    audience: "https://app.example.com/api/vendo/mcp",
    // jwksUri is optional — the door discovers it from the issuer's
    // RFC 8414 metadata when omitted.
  },
});

• Tokens must be ES256-signed JWTs with iss, sub, aud, iat, and exp claims. iss must equal the configured issuer, aud must equal the configured audience, and exp must be in the future.
• The door caches the JWKS in memory and refetches it when a bearer arrives with an unfamiliar kid, which covers ordinary key rotation.
• The door calls oauth.principal(subject) with the JWT sub on every request, so returning null still kills a live session — this remains your revocation point.
• The local /api/vendo/mcp/authorize, /token, and /register endpoints return 404 in this mode, and so does RFC 8414 authorization-server metadata. RFC 9728 protected-resource metadata instead advertises authorization_servers: [remoteAs.issuer], so compliant clients discover and use the external server directly.
• oauth is still required — the door skips oauth.authorize because the external server owns the interactive step, but it still calls oauth.principal.

​

Federate login from an external authorization server

export const vendo = createVendo({
  model,
  principal: resolvePrincipal,
  mcp: true,
  oauth,
  federation: { secret: process.env.VENDO_MCP_FEDERATION_SECRET! },
});

• iss — the external authorization server’s issuer URL.
• aud — the door’s canonical URL (for example https://app.example.com/api/vendo/mcp).
• exp — no more than five minutes in the future.
• jti — a fresh nonce per handshake.
• redirect_uri — where to send the browser after login. Its origin must match iss.
• scopes — the string array the external server wants your user to consent to.
• client_name — the display name shown in your consent UI.

• If your adapter implements authorize, the door calls oauth.authorize(request, { clientName, scopes }). This is the same authorize step your local flow uses, so you do not need a separate consent UI.
• If your adapter is session-only (no authorize), the door calls oauth.session(request, { returnTo }) with the federate request URL as returnTo, so a logged-out user bounces to your login page and resumes the handshake automatically. The external authorization server owns consent, so no in-product consent UI runs.

​

Revoke access

curl -X POST https://app.example.com/api/vendo/mcp/revoke \
  -d "token=<access_or_refresh_token>" \
  -d "client_id=<client_id>" \
  -d "token_type_hint=refresh_token"

​

Saved apps ride along

​

HTTP apps open in-product

{
  "kind": "vendo/open-in-product@1",
  "url": "https://app.example.com/apps/app_123",
  "productName": "Acme",
  "appName": "Sales dashboard"
}

• productName comes from your MCP server identity, so the CTA always names your product.
• appName is best-effort — the door omits it when the app has no title.
• The card themes itself from the same --vendo-* CSS tokens as the consent page, so no extra configuration is needed to match your brand.

​

Host branding crosses the boundary

​

Verify

npx vendo doctor