Quick Start

OpenAPI spec in, MCP server out. Five minutes, zero account required.

Prerequisites

You need Node.js 18+ and an OpenAPI spec (3.0 or Swagger 2.0, JSON or YAML). That's it. No account, no API key, no config file.

Don't have a spec handy?
Use the Petstore sample to follow along:
curl -o petstore.yaml https://petstore3.swagger.io/api/v3/openapi.yaml

Install (optional)

The recommended way to run the CLI is via npx — no install needed. Current version: 0.1.2.

# Recommended: no install needed
npx @migrateforce/cli convert --spec api.yaml --base-url https://api.example.com

# Or install globally
npm install -g @migrateforce/cli
migrateforce convert --spec api.yaml --base-url https://api.example.com
Always use @migrateforce/cli
The only published package is @migrateforce/cli. Running npx @migrateforce convert will fail because @migrateforce is not a published package. Always use npx @migrateforce/cli.

Step 1: Convert

Run the convert command. It reads your spec, maps every endpoint to an MCP tool, and writes a deployable Python server to disk.

npx @migrateforce/cli convert \
  --spec petstore.yaml \
  --base-url https://petstore3.swagger.io/api/v3 \
  --output ./petstore-mcp

You should see output like:

✔ Parsed OpenAPI 3.0 — "Swagger Petstore" (13 endpoints)
✔ Mapped 13 endpoints → 13 MCP tools
✔ Generated MCP server → ./petstore-mcp

Files written:
  main.py              MCP server entry point
  Dockerfile           Container setup
  requirements.txt     Python dependencies
  README.md            Setup and usage docs
  .env.example         Environment variable template
  mcp-manifest.json    Tool definitions for MCP clients

Step 2: Run the server

cd petstore-mcp
cp .env.example .env          # edit if your API needs auth
pip install -r requirements.txt
python main.py

The server starts on localhost:8000 by default. It exposes every mapped endpoint as an MCP tool that any MCP-compatible client (Claude Desktop, Cursor, etc.) can call.

Step 3: Connect to Claude Desktop

Add the server to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "petstore": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/petstore-mcp"
    }
  }
}

Restart Claude Desktop. You now have 13 pet store tools available to the agent.

Done.
You converted a REST API to an MCP server and connected it to an AI agent. Everything ran on your machine — no data left your laptop.

What's Next

A

Add cloud enrichments

Run with --cloud to get a readiness score, improvement advice, and skill catalog matching. Code generation still stays local.

B

Customize the conversion

Filter endpoints with --include / --exclude, preview mappings with --dry-run, or pipe JSON output to other tools.

C

Install a skill

Skills give AI agents domain-specific playbooks for your MCP tools. Browse the catalog, install with one command, customize to fit your workflow.

D

Use the web dashboard

Prefer a visual editor? Upload your spec in the browser, tweak mappings in a table, run the AI Migration Agent, and download the generated server.

CLI Cheat Sheet

# Convert with all defaults
npx @migrateforce/cli convert --spec api.yaml --base-url https://api.example.com

# Preview what will be generated (no files written)
npx @migrateforce/cli convert --spec api.yaml --base-url https://api.example.com --dry-run

# Convert with cloud enrichments
npx @migrateforce/cli convert --spec api.yaml --base-url https://api.example.com --cloud

# Only include GET endpoints
npx @migrateforce/cli convert --spec api.yaml --base-url https://api.example.com \
  --include "GET *"

# Lint your spec for MCP readiness
npx @migrateforce/cli lint api.yaml

# Browse the skill catalog
npx @migrateforce/cli skills list migrateforce/migration-skills

# Install a specific skill
npx @migrateforce/cli skills add migrateforce/migration-skills#mcp-openapi-normalize

# Check your cloud API key status
npx @migrateforce/cli auth status