mcp-manifest

Universal MCP manifest for auto-discovery, validation, and config generation.

The problem: Installing MCP servers requires manual JSON editing, reading READMEs, and guessing config formats. Every client (Claude, Cursor, Windsurf) has a different config file and structure.

The solution: A machine-readable manifest (mcp-manifest.json) that describes how to install, configure, and connect to any MCP server. Clients auto-discover it, users get one-click setup.

Quick Start

# Generate a manifest from your MCP server
npx mcp-manifest init

# Validate it
npx mcp-manifest validate

# Generate Claude Code config from a manifest
npx mcp-manifest convert mcp-manifest.json -c claude --set API_KEY=sk_xxx

# Discover a server's manifest from its URL
npx mcp-manifest discover centralintelligence.online

# Test a server's discovery endpoints
npx mcp-manifest test centralintelligence.online

What's in a Manifest?

{
  "manifest_version": "1.0",
  "server": {
    "name": "My MCP Server",
    "description": "What it does",
    "version": "1.0.0"
  },
  "install": [{ "type": "npm", "package": "my-server", "command": "npx", "args": ["my-server"] }],
  "config": [{ "name": "API_KEY", "required": true, "secret": true, "obtain_url": "https://..." }],
  "transport": { "stdio": { "command": "npx", "args": ["my-server"], "env": { "API_KEY": "{{API_KEY}}" } } },
  "tools": [{ "name": "my_tool", "description": "What it does" }],
  "when_to_use": { "heuristic": "Use when you need persistent storage" },
  "pricing": { "model": "freemium", "free_tier": "100 calls/month" }
}

Commands

mcp-manifest init

Generates mcp-manifest.json from your project's package.json and server.json (MCP registry format).

mcp-manifest validate [file]

Validates a manifest against the JSON Schema. Reports errors and warnings with suggestions.

mcp-manifest discover <url>

Auto-discovers a manifest from:

1. /.well-known/mcp-manifest.json (recommended)
2. <link rel="mcp-manifest"> in HTML
3. Local file

mcp-manifest convert <file> -c <client>

Generates client-specific config. Supported clients:

• claude — ~/.claude/settings.json
• cursor — ~/.cursor/mcp.json
• windsurf — ~/.codeium/windsurf/mcp_config.json
• vscode — ~/.vscode/mcp.json

Use --set KEY=VALUE to fill in config values:

npx mcp-manifest convert mcp-manifest.json -c claude --set API_KEY=sk_xxx

mcp-manifest test <url>

Tests a server's manifest discovery endpoints (well-known URL, HTML link tag).

Hosting Your Manifest

Add to your server's web endpoint:

GET /.well-known/mcp-manifest.json → your manifest JSON

And/or add to your HTML:

<link rel="mcp-manifest" href="/.well-known/mcp-manifest.json">

Schema Extensions Beyond Basic MCP

This manifest spec extends the basic MCP server description with:

• when_to_use — heuristics for when agents should call your server (scenarios, anti-patterns)
• pricing — pricing model, free tier details, x402 payment protocol config
• clients — pre-built config templates for popular MCP clients
• config.obtain_url — where users can get API keys or credentials
• config.prompt — human-readable prompt for interactive setup

Programmatic API

import { validate, generate, discover, convert } from "mcp-manifest";

// Validate
const result = validate(manifestJson);
console.log(result.valid, result.warnings);

// Generate from project
const manifest = generate("./my-mcp-server");

// Discover from URL
const found = await discover("centralintelligence.online");

// Convert to client config
const config = convert(manifest, "claude", { API_KEY: "sk_xxx" });

JSON Schema

The full JSON Schema is at schema/mcp-manifest.schema.json.

Contributing

PRs welcome. Areas we'd love help with:

• Additional client config templates (Cline, Continue, etc.)
• Python/Go/Rust manifest generators
• MCP spec proposal for standardizing the manifest format

License

MIT