fastmcp validate

Validate your FastMCP server file for syntax and structure

The fastmcp validate command checks your server file for TypeScript compilation errors and validates that the FastMCP server is properly structured.

Usage

npx fastmcp validate <file> [options]

Arguments

file · string · required

Path to your FastMCP server file (TypeScript or JavaScript)

Options

--strict · boolean

Enable strict TypeScript validation with type checking

Alias: -s

Default: false

What it validates

The validate command performs two types of checks:

1. TypeScript compilation

   Ensures your server file compiles without TypeScript errors.

   With --strict flag, this uses TypeScript’s strict mode for more thorough type checking.

2. Server structure

   Verifies that your file:

   • Properly imports FastMCP
   • Creates a valid FastMCP instance
   • Exports or starts the server correctly

Examples

Basic validation

Check if your server file is valid:

npx fastmcp validate src/server.ts

Output on success:

[FastMCP] Validating server file: /path/to/src/server.ts
[FastMCP] ✓ TypeScript compilation successful
[FastMCP] ✓ Server structure validation passed
[FastMCP] ✓ All validations passed! Server file looks good.

Strict validation

Enable strict TypeScript checking for more thorough validation:

npx fastmcp validate src/server.ts --strict

This is useful when you want to catch potential type issues before deployment.

Validation in CI/CD

Use validate in your continuous integration pipeline:

GitHub Actions

name: Validate MCP Server
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm install
      - run: npx fastmcp validate src/server.ts --strict

Common errors

File not found

Error: [FastMCP Error] File not found: /path/to/file.ts

Solution: Verify the file path is correct and the file exists.

# Use absolute or relative path
npx fastmcp validate ./src/server.ts

TypeScript compilation failed

Error: [FastMCP] ✗ TypeScript compilation failed

Solution: Fix the TypeScript errors shown in the output. Common issues:

• Missing type imports
• Incorrect type annotations
• Syntax errors

Run with --strict to see all type issues:

npx fastmcp validate src/server.ts --strict

Server structure validation failed

Error: [FastMCP] ✗ Server structure validation failed

Solution: Ensure your file:

1. Imports FastMCP: import { FastMCP } from "fastmcp"
2. Creates an instance: const server = new FastMCP({ ... })
3. Either exports the server or calls server.start()

Example valid structure:

import { FastMCP } from "fastmcp";

const server = new FastMCP({
  name: "My Server",
  version: "1.0.0",
});

// Add tools, resources, prompts...

server.start({ transportType: "stdio" });

Validation vs. Testing

The validate command checks for structural and type correctness but does not:

• Test tool functionality
• Verify runtime behavior
• Check for logical errors

For runtime testing, use the dev command or inspect command.

Exit codes

The validate command uses standard exit codes:

Exit Code	Meaning
0	Validation passed successfully
1	Validation failed or encountered an error

This makes it easy to use in scripts and CI/CD pipelines:

#!/bin/bash
if npx fastmcp validate src/server.ts; then
  echo "✓ Server is valid"
  npm run deploy
else
  echo "✗ Server validation failed"
  exit 1
fi

Best practices

1. Validate before committing

   Add validation to your pre-commit hooks:

   {
     "husky": {
       "hooks": {
         "pre-commit": "npx fastmcp validate src/server.ts"
       }
     }
   }
   
2. Use strict mode in CI

   Enable strict validation in your CI/CD pipeline for maximum type safety:

   npx fastmcp validate src/server.ts --strict
   
3. Validate all server files

   If you have multiple server files, validate them all:

   npx fastmcp validate src/server1.ts && \
   npx fastmcp validate src/server2.ts && \
   npx fastmcp validate src/server3.ts
   

Next steps

Test with dev

Run your server and test it interactively

Debug with inspect

Use visual debugging with MCP Inspector