HTTP / OpenAPI Tool Integration

Pipelines can expose a REST API's operations as individual tools by parsing its OpenAPI specification. Each operation in the spec becomes a callable tool that LLM-response fields can invoke.

How this differs from MCP

At run time the LLM sees the same function-calling interface regardless of which protocol is underneath. You can mix MCP and HTTP bindings on the same LLM field.

Register an HTTP endpoint

1. Navigate to MCP Servers in the sidebar.
2. Click Add Tool Endpoint.
3. Switch to the HTTP (OpenAPI) tab.
4. Fill in the fields:
   • Name (required).
   • Base URL (required) — the base of the API, for example https://api.example.com. This overrides any servers entry in the spec at call time.
   • Description (optional).
5. In OpenAPI Specification, pick one source:
   • From URL — paste a URL to an OpenAPI document (for example https://api.example.com/openapi.json). The platform fetches it on save.
   • Paste — paste the spec text directly. Both JSON and YAML are accepted; the format is auto-detected.
6. Pick an Authentication method:
   • None — no auth headers.
   • API Key — configurable Header Name (default X-API-Key) plus the key value.
   • Bearer Token — sent as Authorization: Bearer <token>.
7. Click Add & Parse Tools.

Finding the OpenAPI spec for an API

If you don't already have the spec, here are the usual ways to locate or produce one, roughly in order of effort.

1. Check the vendor's developer portal. Most API providers publish their OpenAPI / Swagger document on their docs site, often linked as "OpenAPI spec", "Swagger JSON", "API reference (JSON)", or similar. If the docs site is built on tools like Swagger UI, Redoc, or Scalar, the spec URL is almost always one click away.

2. Try well-known paths on the API base URL. Many APIs auto-host the spec at a predictable path. Append one of these to the base URL and see if it returns JSON or YAML:

• /openapi.json, /openapi.yaml
• /swagger.json, /swagger.yaml
• /v3/api-docs (Spring Boot / springdoc)
• /api-docs, /api/docs
• /schema/, /schema.json (DRF, Django Ninja)
• /redoc, /docs (often serves HTML — but the raw spec URL is usually exposed in the page source as a spec-url or url parameter)

3. Look in a public catalog. APIs.guru hosts crowd-sourced OpenAPI specs for thousands of well-known public APIs.

4. Generate one from your own API. If it's an API you control:

• FastAPI / NestJS / ASP.NET / Spring Boot: OpenAPI is generated automatically — it's usually at /openapi.json or /v3/api-docs.
• Express / Flask / Rails: add a library (swagger-jsdoc, flask-smorest, rswag) and generate.
• Postman collection: export it and convert with postman-to-openapi or Postman's built-in "Export as OpenAPI" option.

5. Write a minimal spec by hand. If the API has no published spec and generation isn't feasible, you can hand-write a small OpenAPI 3.x document that covers just the endpoints the LLM should use. The Swagger Editor validates as you type. You only need to describe the operations you want as tools — unused endpoints can be omitted.

Tool discovery from OpenAPI

When you save an HTTP endpoint, Pipelines parses the spec and creates one tool per operation.

• Supported spec versions. OpenAPI 3.0, 3.1, and Swagger 2.0.
• Naming. Tools are named from the operation's operationId, sanitized to [a-zA-Z0-9_-] (max 128 characters; runs of underscores collapsed). When no operationId is present, the tool is named {method}_{path} — for example get_users_id. Duplicates are suffixed with _2, _3, and so on.
• Description. Combined from the operation's summary and description (up to 1024 characters stored).
• Input schema. Built from path parameters, query parameters, and the application/json request body. $refs are resolved up to 10 levels deep.

At call time the LLM sees one schema per operation. Path and query parameters are assigned to their URL positions and JSON-body parameters are sent in the request body automatically based on the spec — you don't remap this from the UI.

Test connection

For HTTP endpoints, Test Connection:

1. Re-parses the spec (from the stored URL or the pasted text).
2. Issues a HEAD request to the Base URL.

Both must succeed for the endpoint to be marked Healthy. If the API doesn't allow HEAD requests, the endpoint may appear unhealthy even when the operations themselves work — run a real pipeline to confirm.

Refresh tools

Refresh Tools behaves differently depending on how the endpoint was registered:

• Registered with a Spec URL. Pipelines re-fetches the URL, re-parses it, and replaces the tool list. Use this to pick up upstream API changes.
• Registered by paste. Pipelines re-parses the stored text. It does not fetch anything. To pick up upstream changes, edit the endpoint and paste the new spec.

In either case, new operations become new tools, and operations that disappeared are removed from the endpoint.

Debugging checklist

1. Parse errors. Confirm the spec is valid JSON or YAML. The Test Connection error message shows where parsing failed.
2. Too few or too many tools. Missing operationIds collapse duplicates via _2 suffixes. Double-check you're looking at the revision you expect.
3. HEAD fails but tools work. Some APIs reject HEAD. Confirm with a live pipeline run.
4. 401/403 on first call. Open Edit on the endpoint and re-enter the key or token (secrets are redacted and can't be re-read). Check the header name if you're using API key auth.
5. Results come back clipped. Per-call results are truncated at 100 KB before being handed back to the LLM. Add filtering or paging in the API if the LLM needs more.