@lovable.dev/mcp-js weekly downloads statistics

@lovable.dev/mcp-js

Author MCP servers for Lovable apps. Declare tools with defineTool, register them with defineMcp, and a Vite plugin emits the framework-specific routes at build time (TanStack today, Supabase Edge Functions next).

// src/lib/mcp/tools/echo.ts
import { defineTool } from "@lovable.dev/mcp-js";
import { z } from "zod";

export default defineTool({
  name: "echo",
  title: "Echo",
  description: "Echo the input text back.",
  inputSchema: { text: z.string().min(1) },
  handler: ({ text }) => ({ content: [{ type: "text", text }] }),
});

// src/lib/mcp/index.ts
import { defineMcp } from "@lovable.dev/mcp-js";
import echoTool from "./tools/echo";

export default defineMcp({
  name: "my-app-mcp",
  title: "My App MCP",
  version: "0.1.0",
  instructions: "Tools for interacting with My App. Use `echo` to verify connectivity.",
  tools: [echoTool],
});

// vite.config.ts
import { defineConfig } from "vite";
import { mcpPlugin } from "@lovable.dev/mcp-js/stacks/tanstack/vite";

export default defineConfig({ plugins: [mcpPlugin()] });

That's the whole authoring surface. No imperative server construction, no route handlers, no JSON-RPC envelope, no transport instantiation — all wrapped.

Manifest extraction allows 512 tools in the evaluated defineMcp({ tools }) array, including conditional and programmatically generated tools. Above that limit, extraction writes the current manifest and exits with an error; reduce the array to 512 tools or fewer. This is an extraction limit, not a runtime cap: the SDK does not truncate tools/list.

inputSchema is closed: a tools/call carrying an argument key the schema does not declare fails in-band (isError: true, naming the key) instead of silently dropping it, and tools/list advertises additionalProperties: false. Set strict: false on a tool to accept and drop unknown keys instead.

What the plugin emits

URL	File	Purpose
POST /mcp	src/routes/mcp.ts	Full MCP streamable-HTTP protocol
GET /.well-known/oauth-protected-resource	src/routes/[.well-known]/oauth-protected-resource.ts	OAuth protected-resource metadata

The table shows the default path: "/mcp"; mcpPlugin({ path: "/api/public/mcp" }) moves the MCP route accordingly.

MCP (POST <path>, /mcp by default) is the wire format clients speak directly. All runtime routes import the same defineMcp result, so they stay in sync on which tools exist and which auth and browser-origin policies protect them. If defineMcp({ auth: ... }) is omitted, the handlers stay unauthenticated; if OAuth auth is configured, clients must pass Authorization: Bearer <token>. Rate limiting belongs at the app host or edge.

The MCP endpoint supports both protocol eras on one URL. Finalized 2026-07-28 clients send the version, client capabilities, and mirrored HTTP headers on every request; the server returns typed results plus cache metadata on discovery and list responses without initialization or protocol sessions. Initialization-era clients continue through a stateless compatibility path: initialize, tools/list, and tools/call work as independent requests, and the endpoint never mints Mcp-Session-Id. GET and DELETE return 405 because there is no standalone stream or session to manage.

Caller-dependent tool catalogs

Use a request context only when authenticated callers must see different tool names. Bind its type once and export the resulting helper for tool files:

// src/lib/mcp/context.ts
import { defineTool } from "@lovable.dev/mcp-js";

export interface AppContext {
  readonly plan: "free" | "pro";
}

export const defineAppTool = defineTool.withAppContext<AppContext>();

Create the app context from verified auth when an operation needs it, then register every tool in the build-time union:

import { auth, defineMcp } from "@lovable.dev/mcp-js";
import type { AppContext } from "./context";
import exportDataTool from "./tools/export-data";

export default defineMcp<AppContext>({
  name: "my-app-mcp",
  title: "My App MCP",
  version: "0.1.0",
  instructions: "Tools for interacting with My App.",
  auth: auth.oauth.issuer({
    issuer: "https://auth.example.com",
    resource: "https://my-app.example.com/mcp",
  }),
  createAppContext: async ({ auth, signal }) => ({
    // Unknown callers get the least-privilege catalog; only a failed lookup throws.
    plan: (await loadPlan(auth.getUserId(), signal)) ?? "free",
  }),
  tools: [exportDataTool],
});

Define conditional tools with the bound helper. The predicate is synchronous and intentionally receives only appContext; handlers receive the same value on ctx.appContext. Keep predicates pure: do not mutate appContext or depend on tool evaluation order.

import { defineAppTool } from "../context";

export default defineAppTool({
  name: "export_data",
  title: "Export data",
  description: "Export the caller's data.",
  enabled: ({ appContext }) => appContext.plan === "pro",
  handler: async (_args, ctx) => {
    const token = ctx.getToken();
    if (!token) throw new Error("Authenticated caller required");
    await exportDataForCaller(token, ctx.signal);
    return { content: [{ type: "text", text: "Export ready." }] };
  },
});
```…