# In your .env file or environment
API_KEY=your-api-key-here
API_BASE_URL=https://api.example.com
```

The generated server automatically includes these in requests to your API.

### When to use openapi-mcp-generator

Choose this tool if you want a basic, standalone MCP server without additional complexity. It's a straightforward CLI that generates TypeScript code from your OpenAPI spec - what you see is what you get. You can edit the generated server code afterward if needed, but there's zero customization during generation beyond choosing transport modes. Best suited for simple use cases where you need a functional MCP server quickly without enterprise features, managed hosting, or advanced tooling.

## Optimizing your OpenAPI document for MCP

Regardless of which tool you choose, the quality of your resulting MCP tools depends on the quality of your OpenAPI document. AI agents need more context than human developers to use APIs effectively.

### Write for AI agents, not just humans

Humans can infer context from brief descriptions. AI agents cannot. Compare these descriptions:

**Basic description** (for humans):

```yaml
get:
  summary: Get task
  description: Retrieve a task by ID
```

**Optimized description** (for AI agents):

```yaml
get:
  summary: Get complete task details
  description: |
    Retrieves full details for a specific task including title, description,
    priority level (low/medium/high), current status, assignee, due date,
    and creation/update timestamps.

    Use this endpoint when you need complete information about a task.
    If you only need a list of task IDs and titles, use listTasks instead.
```

The optimized version tells the AI agent what data to expect in the response, when to use this endpoint vs alternatives, and what each field means (priority values, status types).

### Provide clear parameter guidance

Include examples and explain constraints:

```yaml
parameters:
  - name: task_id
    in: path
    required: true
    schema:
      type: string
      format: uuid
      description: |
        The unique identifier for the task. Must be a valid UUID v4.
        You can get task IDs by calling listTasks first.
      examples:
        example1:
          summary: Valid task ID
          value: "550e8400-e29b-41d4-a716-446655440000"
```

### Add response examples

Example responses help AI agents understand what successful responses look like:

```yaml
responses:
  '200':
    description: Task retrieved successfully
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Task'
        examples:
          complete_task:
            summary: Task with all fields populated
            value:
              id: "550e8400-e29b-41d4-a716-446655440000"
              title: "Review Q4 goals"
              description: "Review and update quarterly objectives"
              priority: "high"
              status: "in_progress"
              assignee: "alice@example.com"
              due_date: "2025-10-15"
              created_at: "2025-10-01T09:00:00Z"
              updated_at: "2025-10-07T14:30:00Z"
```

### Use descriptive operation IDs

Operation IDs become tool names. Make them clear and action-oriented:

```yaml