Build MCP Apps with mcp-use v2

Treat the installed mcp-use package, its generated types, and the project's existing exports as the source of truth. Check the installed version before changing code; do not assume APIs from mcp-use v1.

Workflow

1. Inspect package.json, the server entry, exported tool refs, views/, and the installed mcp-use version.
2. Scaffold a new project with npx create-mcp-use-app@latest; do not hand-build framework boilerplate.
3. Read only the references needed for the task:
   • Server primitives for tools, resources, prompts, middleware, and result envelopes.
   • Views for interactive MCP Apps and React hooks.
   • Authentication for OAuth providers and authenticated tool handlers.
   • Migration when converting v1 code or reviewing package boundaries.
   • Verification before reporting completion.
4. Implement against the package types. Export every statically declared tool ref that a View calls.
5. Validate through the real lifecycle: build/typecheck, run the server, connect a client, call the tool, and render the View when one exists.

Native v2 invariants

• Import server APIs from mcp-use; provider adapters come from mcp-use/oauth/*; React APIs come from mcp-use/react.
• Define tools with inputSchema; add outputSchema when returning structured data or binding a View.
• Return MCP result envelopes with content, structuredContent, and optionally _meta or isError.
• Put each View at views/<name>/view.tsx and bind it with view: { name: "<name>" }.
• Read the rendering call with useToolContext; use focused hooks such as useCallTool, useViewState, useHostContext, and useDisplayMode for additional behavior.
• Export the server as the default export. Let mcp-use dev, build, and start own framework lifecycle and View compilation.
• Keep request state in the request context or an external store. Do not rely on module globals for cross-request identity or elicitation continuity.

Minimal server and View

import { MCPServer } from "mcp-use";
import { z } from "zod";

const server = new MCPServer({ name: "catalog", version: "1.0.0" });

export const showProduct = server.tool(
  {
    name: "show-product",
    description: "Show one catalog product",
    inputSchema: z.object({ id: z.string() }),
    outputSchema: z.object({ id: z.string(), name: z.string() }),
    view: { name: "product" },
  },
  async ({ id }) => {
    const product = { id, name: "Example product" };
    return {
      content: [{ type: "text", text: JSON.stringify(product) }],
      structuredContent: product,
    };
  },
);

export default server;

// views/product/view.tsx
import { ThemeProvider, useToolContext } from "mcp-use/react";

export default function ProductView() {
  const view = useToolContext<"show-product">();
  if (view.status === "pending") return <p>Loading…</p>;
  if (view.status === "error") return <p>{view.error.message}</p>;
  return <ThemeProvider>{view.toolOutput.name}</ThemeProvider>;
}

Guardrails

• Do not copy examples from v1 docs or historical changelogs.
• Do not invent exports or configuration fields; confirm them in installed declarations or source.
• Do not return a plain domain object from a tool callback.
• Do not bind a View without an outputSchema and matching structuredContent.
• Do not claim success from a source build alone when package exports or interactive behavior changed.
• Do not deploy or mutate external systems unless the user explicitly requests it.

Run node <skill-dir>/scripts/check-v2.mjs <project-root> during migrations and reviews, then complete the focused checks in Verification.

Agent Skills

Put reusable agent workflows in skills/<name>/SKILL.md; the directory is served automatically, so normally omit the skills server option. Use skills: false to disable it or skills: { directory: "server-skills" } to override the project-relative directory. Keep supporting references, scripts, templates, and assets in the skill instead of inflating tool descriptions.