OpenAPI MCP Servers

:::caution[Experimental] OpenAPI to MCP conversion is currently in beta. The API may change. ::: Station can automatically convert OpenAPI/Swagger specifications into MCP servers, making any REST API instantly available as agent tools.

How It Works

OpenAPI Spec ──stn openapi-runtime──> MCP Server ──> Agent Tools
     │                                    │
     └── Paths become tools ──────────────┘

Station reads your OpenAPI spec and exposes each endpoint as an MCP tool.

Quick Start

1. Add OpenAPI Spec to Bundle

{
  "name": "My API Tools",
  "description": "Tools from my REST API",
  "mcpServers": {
    "my-api": {
      "command": "stn",
      "args": [
        "openapi-runtime",
        "--spec",
        "environments/{{ .ENVIRONMENT_NAME }}/my-api.openapi.json"
      ]
    }
  },
  "metadata": {
    "openapiSpec": "my-api.openapi.json",
    "variables": {
      "API_BASE_URL": {
        "description": "Base URL for the API",
        "default": "https://api.example.com"
      }
    }
  }
}

2. Use Template Variables

Your OpenAPI spec can use template variables:

{
  "openapi": "3.0.0",
  "info": {
    "title": "My API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "{{ .API_BASE_URL }}",
      "description": "API endpoint"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "operationId": "listUsers",
        "summary": "List all users"
      }
    }
  }
}

3. Assign to Agent

---
metadata:
  name: "api-manager"
tools:
  - "__listUsers"      # From OpenAPI spec
  - "__createUser"
  - "__getUserById"
---

Station Admin Example

Create an agent that manages Station itself using the Station API:

OpenAPI Spec

{
  "openapi": "3.0.0",
  "info": {
    "title": "Station Management API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "{{ .STATION_API_URL }}",
      "description": "Station API endpoint"
    }
  ],
  "paths": {
    "/api/v1/environments": {
      "get": {
        "operationId": "listEnvironments",
        "summary": "List all environments"
      }
    },
    "/api/v1/agents": {
      "get": {
        "operationId": "listAgents",
        "summary": "List all agents"
      },
      "post": {
        "operationId": "createAgent",
        "summary": "Create a new agent"
      }
    },
    "/api/v1/agents/{id}": {
      "get": {
        "operationId": "getAgent",
        "summary": "Get agent by ID"
      }
    },
    "/api/v1/agents/{id}/execute": {
      "post": {
        "operationId": "executeAgent",
        "summary": "Execute an agent"
      }
    }
  }
}

Agent Definition

---
metadata:
  name: "station-admin"
  description: "Manages Station environments, agents, and MCP servers"
model: gpt-4o-mini
max_steps: 10
tools:
  - "__listEnvironments"
  - "__listAgents"
  - "__getAgent"
  - "__createAgent"
  - "__executeAgent"
---

{{role "system"}}
You are a Station administrator. Use the Station API tools to:
- List and inspect environments and agents
- Create new agents from user requirements
- Execute agents and monitor their runs

{{role "user"}}
{{userInput}}

Usage

stn agent run station-admin "Show me all environments and their agents"

Features

Automatic Tool Generation

Each OpenAPI path becomes an MCP tool:

OpenAPI	MCP Tool
`GET /users`	`__listUsers` (from operationId)
`POST /users`	`__createUser`
`GET /users/{id}`	`__getUserById`
`DELETE /users/{id}`	`__deleteUser`

Template Variable Resolution

Variables in {{ .VAR }} format are resolved from:

variables.yml in the environment
Environment variables
Default values in metadata

Authentication Support

{
  "securityDefinitions": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "security": [
    {"bearerAuth": []}
  ]
}

Configure via variables:

# variables.yml
API_AUTH_TOKEN: "{{ .API_AUTH_TOKEN }}"

Smart Tool Sync

Station detects OpenAPI spec changes and refreshes tools automatically.

Configuration

Bundle Manifest

{
  "name": "API Integration Bundle",
  "mcpServers": {
    "my-api": {
      "command": "stn",
      "args": [
        "openapi-runtime",
        "--spec", "my-api.openapi.json",
        "--base-url", "{{ .API_BASE_URL }}"
      ],
      "env": {
        "API_TOKEN": "{{ .API_TOKEN }}"
      }
    }
  },
  "metadata": {
    "openapiSpec": "my-api.openapi.json",
    "variables": {
      "API_BASE_URL": {
        "description": "API base URL",
        "required": true
      },
      "API_TOKEN": {
        "description": "API authentication token",
        "secret": true
      }
    }
  }
}

Runtime Options

stn openapi-runtime \
  --spec path/to/spec.json \
  --base-url https://api.example.com \
  --header "Authorization: Bearer $TOKEN" \
  --timeout 30

Supported Features

OpenAPI Feature	Support
OpenAPI 3.0	✅ Full
OpenAPI 3.1	✅ Full
Swagger 2.0	✅ Converted
JSON specs	✅
YAML specs	✅
$ref resolution	✅
allOf/oneOf/anyOf	✅
Bearer auth	✅
API key auth	✅
OAuth2	⚠️ Partial

Best Practices

Use operationId - Explicit IDs make cleaner tool names
Write good summaries - Used as tool descriptions
Define schemas - Better type information for agents
Use template variables - Keep credentials out of specs
Version your specs - Track API changes in Git

Limitations

No webhooks - Only request/response patterns
No streaming - Standard HTTP only
Limited OAuth - Manual token management required
Schema complexity - Very complex schemas may simplify

Troubleshooting

Tool Not Found

Error: tool __myOperation not found

Check:

operationId is defined in spec
Spec file path is correct
Run stn tools list to see available tools

Authentication Errors

Error: 401 Unauthorized

Check:

Token is set in variables.yml or environment
Security scheme matches your auth method
Token hasn’t expired

Schema Validation Errors

Error: invalid request body

Check:

Request schema matches API expectations
Required fields are provided
Types match (string vs number)

Next Steps

MCP Tools - All available tools
Bundles - Package with OpenAPI specs
Fakers - Mock your APIs for testing

Get Started

Station CLI

Building Agents

Station Lattice

Deployment

Advanced

OpenAPI MCP Servers

OpenAPI MCP Servers

How It Works

Quick Start

1. Add OpenAPI Spec to Bundle

2. Use Template Variables

3. Assign to Agent

Station Admin Example

OpenAPI Spec

Agent Definition

Usage

Features

Automatic Tool Generation

Template Variable Resolution

Authentication Support

Smart Tool Sync

Configuration

Bundle Manifest

Runtime Options

Supported Features

Best Practices

Limitations

Troubleshooting

Tool Not Found

Authentication Errors

Schema Validation Errors

Next Steps

​OpenAPI MCP Servers

​How It Works

​Quick Start

​1. Add OpenAPI Spec to Bundle

​2. Use Template Variables

​3. Assign to Agent

​Station Admin Example

​OpenAPI Spec

​Agent Definition

​Usage

​Features

​Automatic Tool Generation

​Template Variable Resolution

​Authentication Support

​Smart Tool Sync

​Configuration

​Bundle Manifest

​Runtime Options

​Supported Features

​Best Practices

​Limitations

​Troubleshooting

​Tool Not Found

​Authentication Errors

​Schema Validation Errors

​Next Steps

OpenAPI MCP Servers

How It Works

Quick Start

1. Add OpenAPI Spec to Bundle

2. Use Template Variables

3. Assign to Agent

Station Admin Example

OpenAPI Spec

Agent Definition

Usage

Features

Automatic Tool Generation

Template Variable Resolution

Authentication Support

Smart Tool Sync

Configuration

Bundle Manifest

Runtime Options

Supported Features

Best Practices

Limitations

Troubleshooting

Tool Not Found

Authentication Errors

Schema Validation Errors

Next Steps