FastMCP Framework

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js to a dynamic import()

  cause Attempting to use `require()` to import FastMCP or its dependencies in a CommonJS context, but the package is ESM-first.
  fix Update your project to use ES module `import` syntax (`import { Name } from 'pkg';`) or ensure your Node.js environment is configured for ESM. If using a CommonJS file, you might need to use `import()` dynamically or convert the file to ESM.

• ZodError: [ { "code": "invalid_type", "expected": "number", "received": "string", "path": [ "a" ], "message": "Expected number, received string" } ]

  cause Input parameters provided to a tool or prompt do not match the defined Zod schema.
  fix Review the schema definition (e.g., `z.object(...)`) for the tool or prompt and ensure that the arguments passed when calling it conform to the expected types and structure. Check for missing required fields or incorrect data types.

• Error: OAuthProxy: The 'redirect_uri' provided is not valid. It must be one of the registered URIs.

  cause The `redirect_uri` used in an OAuth authorization request does not match the URI(s) registered with your OAuth provider or the FastMCP `OAuthProxy` configuration. This became a stricter validation in v4.0.0.
  fix Ensure the `redirect_uri` in your client's OAuth request precisely matches one of the URIs configured in your OAuth provider's settings and within your `FastMCP` server's `OAuthProxy` setup. Pay close attention to trailing slashes and subpaths.

Warnings

• breaking Version 4.0.0 introduced a breaking change related to authentication, specifically validating `redirect_uri` in `OAuthProxy.authorize` to fix a CWE-601 vulnerability. Ensure your OAuth configurations comply with the new strict validation.
  Fix: Review and update your OAuth `redirect_uri` configurations to ensure they are valid and correctly configured according to security best practices. Consult the release notes for specific migration details.
• breaking FastMCP's versioning policy permits breaking changes in minor versions, unlike traditional semantic versioning. This is due to the rapid evolution of the underlying MCP ecosystem. Developers should anticipate and actively review release notes for minor version updates.
  Fix: Carefully review release notes for every minor version update (`X.Y.0`) to identify and implement necessary code adjustments. Pin dependencies to specific versions for production stability if frequent breaking changes are problematic.
• breaking The `fastmcp.server.auth` module is explicitly exempted from standard compatibility guarantees and is prone to breaking changes, even in patch versions. This is due to the fast-evolving nature of MCP authentication specifications.
  Fix: If using authentication features, especially the `OAuthProxy` or related `auth` modules, closely monitor patch releases and consider pinning your FastMCP dependency to a specific patch version in production environments until your authentication setup is stable.
• gotcha There is a Python implementation also named 'FastMCP' (prefecthq/fastmcp). This entry specifically refers to the TypeScript framework (punkpeye/fastmcp-ts). Ensure you are using the correct library for your project language.
  Fix: Verify your project's `package.json` and import statements to confirm you are installing and using `fastmcp` (TypeScript) for JavaScript/TypeScript projects, not the Python equivalent.

Install

• npm install firecrawl-fastmcp npm
• yarn add firecrawl-fastmcp yarn
• pnpm add firecrawl-fastmcp pnpm

Imports

• FastMCP
  wrong:

  const FastMCP = require('fastmcp');

  correct:

  import { FastMCP } from 'fastmcp';

  FastMCP is an ESM-first package. Use ES module `import` syntax.
• z
  wrong:

  const z = require('zod');

  correct:

  import { z } from 'zod';

  Zod is the recommended schema validation library. Ensure it's imported correctly.
• GoogleProvider
  wrong:

  import GoogleProvider from 'fastmcp/auth/google'; // Older or incorrect path

  correct:

  import { GoogleProvider } from 'fastmcp';

  Authentication providers like `GoogleProvider` are typically named exports from the main `fastmcp` package.

Quickstart

This quickstart demonstrates how to initialize a FastMCP server, add a type-safe tool for arithmetic operations, define a reusable prompt, and start the server using HTTP streaming transport, including basic session logging.

import { FastMCP, FastMCPSession } from "fastmcp";
import { z } from "zod";

const server = new FastMCP({
  name: "My CalculatMCP",
  version: "1.0.0",
  // Configure logging to see server activity
  loggingLevel: "debug",
  // Enable ping to keep connections alive, useful for long-running sessions
  ping: {
    enabled: true,
    intervalMs: 15000 // Ping every 15 seconds
  }
});

server.addTool({
  name: "add",
  description: "Add two numbers and return the sum",
  parameters: z.object({
    a: z.number().describe("The first number to add"),
    b: z.number().describe("The second number to add")
  }),
  execute: async (args: { a: number; b: number }, { session }: { session: FastMCPSession }) => {
    // Log the operation within the session context
    session.info(`Executing 'add' tool for numbers: ${args.a} and ${args.b}`);
    return `The sum of ${args.a} and ${args.b} is ${args.a + args.b}.`;
  }
});

server.addPrompt({
  name: "greetUser",
  description: "A reusable prompt to greet a user by name.",
  parameters: z.object({
    name: z.string().describe("The name of the user to greet.")
  }),
  render: async (args: { name: string }) => {
    return `Hello, ${args.name}! Welcome to FastMCP.`;
  }
});

// Start the server, listening for connections
server.start({
  transportType: "httpStream", // Or "stdio" for local testing with MCP CLI
  httpStream: {
    port: 8080,
    endpoint: "/mcp"
  }
});

console.log("FastMCP server started on http://localhost:8080/mcp");
console.log("Use a compatible MCP client or inspector to interact.");