Shaping Curated MCP Servers

# Plain OpenAPI: no extra annotations needed
security:
  - api_key: []                      # Applied by the runtime from API_KEY

paths:
  /orders:
    post:
      operationId: placeOrder        # Tool "place_order"
      summary: Place a new order     # Tool description
      parameters:
        - name: Authorization        # Stripped: never a tool argument
          in: header
          schema: { type: string }
      requestBody:                   # Tool argument "body", full JSON Schema
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/NewOrder" }
      # POST: readOnlyHint false, so hosts can ask before running it

  /orders/{orderId}:
    get:
      operationId: getOrder          # Read-only tool "get_order"
      summary: Get an order

  /currencies:
    get:
      operationId: getCurrencies     # Resource "reference://currencies"
      summary: List supported currencies

  /admin/database/vacuum:
    post:
      summary: Trigger internal database maintenance
      x-internal: true               # Excluded

  /orders/legacy:
    get:
      summary: Legacy order list
      deprecated: true               # Excluded

components:
  securitySchemes:
    api_key:                         # Copied into the manifest's sources
      type: apiKey
      in: header
      name: X-API-Key

{
  "name": "place_order",
  "description": "Place a new order",
  "inputSchema": {
    "type": "object",
    "properties": {
      "body": {
        "type": "object",
        "required": ["customerId", "items"],
        "properties": {
          "customerId": { "type": "string" },
          "items": { "type": "array", "items": { "type": "string" } },
          "shippingMethod": { "type": "string", "enum": ["standard", "express", "overnight"] }
        }
      }
    },
    "required": ["body"]
  },
  "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false },
  "operation": {
    "source": "api",
    "method": "POST",
    "path": "/orders",
    "params": [{ "name": "body", "in": "body", "contentType": "application/json" }],
    "security": [{ "api_key": [] }]
  }
}

# The zip: manifest.json, runtime.js, server.ts, package.json, README.md, claude_desktop_config.json
# (and workflow-runtime.js when the page has a <rapi-flow> with workflows)
unzip my-api-mcp.zip -d my-api-mcp
cd my-api-mcp
npm install

# One environment variable per security scheme (upper snake case); API_KEY is the fallback
API_KEY="your-key" npm start        # runs: tsx server.ts

# Point the server at another environment
API_BASE_URL="https://staging.example.com/v2" API_KEY="your-key" npm start

<!-- 1. Enable the Export MCP Server button in the API overview -->
<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>

<rapi-doc
  spec-url="/specs/my-api.yaml"
  mcp="true"
  mcp-server-name="my-api-mcp"
  theme="slate"
> </rapi-doc>

// Access the RapiDoc custom element in JavaScript
const doc = document.querySelector('rapi-doc');

// 1. Build the manifest, the project files and the host configuration in memory
const result = doc.generateMcpServer({ serverName: 'my_api_mcp' });
console.log(result.manifest.tools);       // [{ name, description, inputSchema, annotations, operation }]
console.log(result.files['server.ts']);   // also manifest.json, runtime.js, package.json, README.md, ...
console.log(result.hostConfig);           // Claude Desktop / Cursor JSON config
console.log(result.budget);               // { totalTools: 5, estimatedTokens: 850, ... }

// 2. Download the project as <server-name>-mcp.zip
doc.downloadMcpServer();

// 3. Inspect token budget overhead before exporting
const budget = doc.getMcpBudget();
console.log(`Overhead: ~${budget.estimatedTokens} tokens/turn across ${budget.totalTools} tools`);