# Read and write, but not destructive operations
npx mcp start --scope read --scope write
```

If you're using Claude Desktop, you can also specify scopes in the config:

```json
{
  "mcpServers": {
    "RacingLapCounter": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "racing-lap-counter",
        "--",
        "mcp",
        "start",
        "--scope",
        "read",
        "--scope",
        "write"
      ]
    }
  }
}
```

#### Apply scopes across multiple operations

To apply scopes consistently across many operations, you can use the global `x-speakeasy-mcp` extension:

```yaml
x-speakeasy-mcp:
  scope-mapping:
    - pattern: "^get|^list"
      scopes: [read]
    - pattern: "^create|^update"
      scopes: [write]
    - pattern: "^delete"
      scopes: [write, destructive]
```

This automatically applies scopes based on operation name patterns, saving you from manually tagging each endpoint.

### Add detailed parameter descriptions and examples

To make it easier for AI models to understand your MCP tools, provide detailed descriptions for each parameter. This includes specifying the expected format, constraints, and examples. This helps the LLM choose the right tools when it needs to follow a step-by-step approach to accomplish a task.

```yaml filename="openapi.yaml"
parameters:
  - name: driver_id
    in: path
    required: true
    schema:
      type: string
      description: |
        The UUID of the driver to retrieve. Must be a valid UUID v4 format.
      format: uuid
      examples:
        hamiltonExample:
          summary: Lewis Hamilton's ID
          value: f1a52136-5717-4562-b3fc-2c963f66afa6
        verstappenExample:
          summary: Max Verstappen's ID
          value: c4d85b23-9fe2-4219-8a30-72ef172e327b
      title: Driver Id
    description: The UUID of the driver to retrieve
    x-speakeasy-mcp:
      description: |
        The unique identifier for the driver. You can find the IDs of current F1 drivers
        by first using the listDrivers tool. Common drivers include Lewis Hamilton,
        Max Verstappen, and Charles Leclerc.
```

### Add examples to responses

To improve the LLM's understanding of your API's responses, provide detailed descriptions, examples, and expected structures. This helps the LLM accurately interpret the data returned by your API.

```yaml filename="openapi.yaml"
responses:
  "200":
    description: |
      Lap records retrieved successfully, sorted from fastest to slowest lap time.
      Returns an empty array if the driver exists but has no recorded laps.
    content:
      application/json:
        schema:
          type: array
          items:
            "$ref": "#/components/schemas/Lap"
          title: DriverLapsResponse
        examples:
          multipleLaps:
            summary: Multiple lap records
            value:
              - id: "3fa85f64-5717-4562-b3fc-2c963f66afa7"
                lap_time: 85.4
                track: "Silverstone"
              - id: "3fa85f64-5717-4562-b3fc-2c963f66afa8"
                lap_time: 86.2
                track: "Monza"
          emptyLaps:
            summary: No lap records
            value: []
    x-speakeasy-mcp:
      name: "get_driver_lap_records"
      description: |
        Returns an array of lap records for the requested driver. Each record contains:
        - id: A unique identifier for the lap record
        - lap_time: Time in seconds (lower is better)
        - track: Name of the circuit where the lap was recorded

        The records are sorted from fastest to slowest lap time. If the driver exists
        but hasn't completed any laps, this will return an empty array.
```

## Conclusion

Generating MCP servers from OpenAPI documents bridges the gap between your existing APIs and AI agents. With an OpenAPI document you can have a working MCP server in minutes instead of days.

While this guide focuses on optimizing your OpenAPI document for MCP servers, these techniques are also good practice for writing well-structured, high-quality, comprehensive OpenAPI documents with great developer experience.

Ready to get started? Try [Gram](https://app.getgram.ai) for instant managed hosting, explore [FastMCP](https://github.com/jlowin/fastmcp) for Python-based development, or use [openapi-mcp-generator](https://github.com/harsha-iiiv/openapi-mcp-generator) for a self-hosted TypeScript solution.

For more information on how to improve your OpenAPI document, check out our [OpenAPI best practices guide](/docs/prep-openapi/best-practices).