Skip to main content
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 checkingAlias: -sDefault: 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: 
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

Error: [FastMCP Error] File not found: /path/to/file.tsSolution: Verify the file path is correct and the file exists.
# Use absolute or relative path
npx fastmcp validate ./src/server.ts
Error: [FastMCP] ✗ TypeScript compilation failedSolution: 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
Error: [FastMCP] ✗ Server structure validation failedSolution: 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 CodeMeaning
0Validation passed successfully
1Validation 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

Build docs developers (and LLMs) love

Get started for freeTalk to us