OpenAPI Hurl

You run an MCP server that connects OpenAPI specifications with Hurl test scripting, enabling AI tools to load, inspect, and generate Hurl tests from API schemas. This server design lets you explore endpoints, security schemes, and request/response structures while producing ready-to-run Hurl snippets for automated testing.

How to use

Set up your MCP client to communicate with the OpenAPI Hurl MCP server. You will load OpenAPI specifications, inspect schemas and routes, retrieve security definitions, and fetch Hurl documentation to guide test creation and learning.

Typical workflows you can perform include loading a specification from a local file or remote URL, listing available schemas, retrieving specific request and response schemas for endpoints, and obtaining Hurl documentation sections to assist in writing tests.

To start from a local development environment, use the provided MCP configuration which runs the server via Bun. This keeps the server self-contained and easy to test locally.

How to install

Prerequisites you need installed on your machine before running the MCP server:

• Bun v1.3.0 or higher

Follow these steps to set up the server locally:

# 1. Clone the project repository
git clone <repository-url>
cd hurl-openapi-mcp

# 2. Install dependencies
bun install

# 3. Start the MCP server via stdio (see configuration below)

Configuration example

Configure your MCP client to run the server using Bun. The following example shows a typical MCP configuration entry for stdio usage.

{
  "mcpServers": {
    "openapi_hurl": {
      "command": "bun",
      "args": [
        "run",
        "/home/oung/Projects/bun/hurl-openapi-mcp/src/index.ts"
      ]
    }
  }
}

Usage patterns

1. Load a specification from a local file or a URL, then list schemas or retrieve details for specific schemas, routes, and security schemes.

2. Inspect route information to understand available endpoints, HTTP methods, and associated request/response schemas.

3. Retrieve Hurl documentation sections to learn file structure, request/response formats, capturing and asserting responses, and available grammar references.

Notes on usage

The server runs over stdio by default, enabling you to connect it to any MCP-compatible client. Use the configuration example above to start the server in your local environment.

Additional sections

Security and access controls are defined within the OpenAPI specifications you load. You can retrieve security scheme details to understand authentication and authorization requirements for each endpoint.

Examples and learning resources for Hurl documentation are accessible through the Hurl documentation sections, which cover file structure, requests, responses, capturing techniques, assertions, filters, and grammar references.

Troubleshooting

If you encounter issues starting the server, verify that Bun is installed and the specified index.ts file path exists. Ensure that you are using the stdio configuration with a valid Bun command and path.

Notes

This MCP server focuses on bridging OpenAPI specifications with Hurl testing workflows, enabling automated API testing, documentation generation, and schema inspection through MCP-compatible tooling.

Available tools

specifications:add

Load OpenAPI specifications from JSON or YAML files (local or remote) into the MCP server.

specifications:list

List all loaded OpenAPI specifications to understand what schemas and routes are available.

schemas:list

Get all schema names from a specified OpenAPI spec to discover available data models.

schemas:retrieve

Retrieve details of a specific schema from an OpenAPI spec for precise structure and constraints.

security:list

Get all security schemes from a specified OpenAPI spec to understand authentication methods.

security:retrieve

Retrieve details of a specific security scheme from an OpenAPI spec.

routes:list

List all available routes with their HTTP methods from a specified OpenAPI spec.

routes:retrieve

Retrieve detailed information about a specific route or endpoint.

requests:retrieve

Retrieve the request schema for a specific endpoint from an OpenAPI 3.x specification.

responses:retrieve

Retrieve the response schema for a specific endpoint from an OpenAPI 3.x specification.

hurl_document:retrieve

Retrieve Hurl documentation sections including file structure, entry definitions, request/response structures, and grammar references.