{"id":10895,"library":"firecrawl-fastmcp","title":"FastMCP Framework","description":"FastMCP is an opinionated TypeScript framework for efficiently building Model Context Protocol (MCP) servers, currently stable at version 4.0.0. It aims to simplify the creation of MCP servers by abstracting away low-level implementation details, handling boilerplate, and providing intuitive, high-level APIs for common tasks like tool, resource, and prompt definition, authentication, and session management. The project maintains a rapid release cadence, often shipping minor versions every 3-4 weeks and immediately releasing patch versions for critical bug fixes and security updates, reflecting its commitment to staying current with the evolving MCP ecosystem. Key differentiators include built-in OAuth 2.1 authentication (with support for Google, GitHub, Azure, and custom providers), comprehensive session management, multiple transport options (HTTP streaming, SSE, stdio), edge runtime support, and custom HTTP route capabilities. It is designed for developers who want to quickly build robust MCP servers without delving into the intricacies of the underlying MCP SDK, on which it is built.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/punkpeye/fastmcp","tags":["javascript","MCP","SSE","typescript"],"install":[{"cmd":"npm install firecrawl-fastmcp","lang":"bash","label":"npm"},{"cmd":"yarn add firecrawl-fastmcp","lang":"bash","label":"yarn"},{"cmd":"pnpm add firecrawl-fastmcp","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for defining and validating tool and prompt schemas, though other Standard Schema compliant libraries like ArkType or Valibot are also supported.","package":"zod","optional":false},{"reason":"Optional dependency for JSON Web Key Set (JWKS) support (RS256/ES256 token verification) when using the OAuth Proxy.","package":"jose","optional":true}],"imports":[{"note":"FastMCP is an ESM-first package. Use ES module `import` syntax.","wrong":"const FastMCP = require('fastmcp');","symbol":"FastMCP","correct":"import { FastMCP } from 'fastmcp';"},{"note":"Zod is the recommended schema validation library. Ensure it's imported correctly.","wrong":"const z = require('zod');","symbol":"z","correct":"import { z } from 'zod';"},{"note":"Authentication providers like `GoogleProvider` are typically named exports from the main `fastmcp` package.","wrong":"import GoogleProvider from 'fastmcp/auth/google'; // Older or incorrect path","symbol":"GoogleProvider","correct":"import { GoogleProvider } from 'fastmcp';"}],"quickstart":{"code":"import { FastMCP, FastMCPSession } from \"fastmcp\";\nimport { z } from \"zod\";\n\nconst server = new FastMCP({\n  name: \"My CalculatMCP\",\n  version: \"1.0.0\",\n  // Configure logging to see server activity\n  loggingLevel: \"debug\",\n  // Enable ping to keep connections alive, useful for long-running sessions\n  ping: {\n    enabled: true,\n    intervalMs: 15000 // Ping every 15 seconds\n  }\n});\n\nserver.addTool({\n  name: \"add\",\n  description: \"Add two numbers and return the sum\",\n  parameters: z.object({\n    a: z.number().describe(\"The first number to add\"),\n    b: z.number().describe(\"The second number to add\")\n  }),\n  execute: async (args: { a: number; b: number }, { session }: { session: FastMCPSession }) => {\n    // Log the operation within the session context\n    session.info(`Executing 'add' tool for numbers: ${args.a} and ${args.b}`);\n    return `The sum of ${args.a} and ${args.b} is ${args.a + args.b}.`;\n  }\n});\n\nserver.addPrompt({\n  name: \"greetUser\",\n  description: \"A reusable prompt to greet a user by name.\",\n  parameters: z.object({\n    name: z.string().describe(\"The name of the user to greet.\")\n  }),\n  render: async (args: { name: string }) => {\n    return `Hello, ${args.name}! Welcome to FastMCP.`;\n  }\n});\n\n// Start the server, listening for connections\nserver.start({\n  transportType: \"httpStream\", // Or \"stdio\" for local testing with MCP CLI\n  httpStream: {\n    port: 8080,\n    endpoint: \"/mcp\"\n  }\n});\n\nconsole.log(\"FastMCP server started on http://localhost:8080/mcp\");\nconsole.log(\"Use a compatible MCP client or inspector to interact.\");","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.x.x"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.12.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` to import FastMCP or its dependencies in a CommonJS context, but the package is ESM-first.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of index.js to a dynamic import()"},{"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.","cause":"Input parameters provided to a tool or prompt do not match the defined Zod schema.","error":"ZodError: [ { \"code\": \"invalid_type\", \"expected\": \"number\", \"received\": \"string\", \"path\": [ \"a\" ], \"message\": \"Expected number, received string\" } ]"},{"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.","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.","error":"Error: OAuthProxy: The 'redirect_uri' provided is not valid. It must be one of the registered URIs."}],"ecosystem":"npm"}