Local vs Cloud | MigrateForce Documentation | MigrateForce Documentation

The Split

MigrateForce has a clear boundary between what runs locally and what runs in the cloud. This is a deliberate design choice: your OpenAPI spec and generated code stay on your machine. The cloud provides value-add analysis that you can take or leave.

Capability	Local	Cloud
OpenAPI parsing & validation	✓	—
Endpoint extraction	✓	—
Tool name generation	✓	✓ (enhanced suggestions)
MCP server code generation	✓	—
File writing (main.py, Dockerfile, etc.)	✓	—
MCP readiness linting (score 0–100)	—	✓
Improvement advice	—	✓
Skill catalog matching	—	✓
Project creation & history	—	✓

Key principle

No generated code ever leaves your machine. When you use --cloud, the CLI sends your spec to the MigrateForce API for analysis, receives enrichment data back, then generates files locally using the enriched mappings. The cloud endpoint returns analysis — not code.

Local Mode (default)

When you run npx @migrateforce/cli convert without --cloud, everything happens on your machine. The CLI uses the @migrateforce/mcp package to parse the spec, generate tool names, and produce the MCP server code. No network calls.

npx @migrateforce/cli convert \
  --spec openapi.yaml \
  --base-url https://api.example.com \
  --output ./my-mcp-server

This is the right choice when you want speed, offline operation, or zero trust requirements.

Cloud Mode

Add --cloud to send your spec to the MigrateForce API for analysis. You get back four things that local mode doesn't provide:

Readiness Score (0–100)

How well your spec is structured for MCP conversion. Deductions for missing descriptions, unnamed operations, ambiguous paths. Anything below 40 gets flagged as a blocker.

Improvement Advice

Concrete suggestions for improving your spec. Example: "Add operationId to POST /users — without it, the tool name defaults to a generic create_users."

Skill Matches

Domain-specific skills from the MigrateForce catalog that match your API. If you're converting a healthcare API, the system might suggest patient-intake-automation or hipaa-compliance-check.

Project Tracking

Add --save-project alongside --cloud to save the conversion as a project in the web dashboard. You can revisit it later, edit mappings, or run the Migration Agent.

Setting Up Cloud Mode

You need an API key. Get one from your dashboard settings.

# Set your API key (one-time setup)
npx @migrateforce/cli auth login

# Verify it works
npx @migrateforce/cli auth status

Then convert with cloud enrichments:

npx @migrateforce/cli convert \
  --spec openapi.yaml \
  --base-url https://api.example.com \
  --cloud \
  --output ./my-mcp-server

The output includes both the generated files (same as local) and a cloud enrichment summary:

✔ Parsed OpenAPI 3.0 — "My API" (24 endpoints)
✔ Cloud enrichments received

  Readiness Score: 78/100
  Issues: 2 warnings, 1 info
  Advice:
    • Add descriptions to 3 endpoints missing summaries
    • Consider splitting /admin/* into a separate spec

  Matched Skills:
    • mcp-openapi-normalize — Normalizes specs for better tool generation
    • crm-data-sync — CRM data synchronization patterns

✔ Mapped 24 endpoints → 24 MCP tools
✔ Generated MCP server → ./my-mcp-server

What Gets Sent to the Cloud

When you use --cloud, the CLI sends your OpenAPI spec (the JSON/YAML content) and the base URL to POST /api/cli/convert. That's it. The API analyzes the spec and returns enrichments. It does not:

✗Generate or return any code

✗Store your spec permanently (unless you opt into project creation)

✗Send your spec to third parties

✗Access your file system or network

API Key Scopes

API keys have scoped permissions. The key generated on your dashboard settings page includes:

Scope	Allows
convert	Send specs for analysis, receive enrichments
lint	Run cloud-side linting and readiness scoring
skills	Search and read from the skill catalog

When to Use Which

Use Local When

• You're offline or on an air-gapped network

• You don't want to share your spec with any external service

• Speed matters — local is faster (no network round-trip)

• You're in CI/CD and don't want API key management

• The spec is straightforward and you don't need quality advice

Use Cloud When

• You want a quality score before shipping

• Your spec is large and you need guidance on what to fix

• You want skill recommendations for your API domain

• You want to save the project for later editing in the dashboard

• You're onboarding a team and want consistent quality baselines

Both modes produce the same output files

The 6 generated files (main.py, Dockerfile, etc.) are identical whether you run local or cloud. Cloud mode just prints additional analysis alongside them.

Next: Deep dive into the convert command — filtering endpoints, dry-run previews, JSON output mode, and integration with CI pipelines.