Why teams use it
Most SaaS platforms and internal services describe their REST APIs with an OpenAPI spec, but far fewer ship an MCP server on top of it. Without SpecLink, connecting one of those APIs to your agents means waiting for the vendor to build MCP support or building and hosting a translation layer yourself. SpecLink removes that step. Point it at a spec and the base URL of the API it describes, and Airia:- Reads the spec and generates a tool for each operation it defines.
- Keeps the connection ready to use, alongside your other custom servers.
- Sends every generated tool’s requests to the Upstream API Base URL, not the spec URL.
Set up SpecLink
Start a new custom server
Begin a new custom server and fill in the Basic Information step as usual.
Choose the SpecLink transport
On the Remote Configuration step, set Transport Type to Hosted YAML (OpenAPI spec).
Enter the two URLs SpecLink needs
| Field | Description |
|---|---|
| OpenAPI YAML URL | Where your OpenAPI/Swagger spec is hosted. Must be an HTTPS URL. |
| Upstream API Base URL | The base URL of the actual API the spec describes, for example https://api.example.com/v1. Must also be HTTPS. |
The OpenAPI YAML URL must link directly to the raw YAML (or JSON) document, not to a web page that displays or wraps it. For a spec hosted on GitHub, use the 
raw.githubusercontent.com link rather than the github.com/blob/... page. Opening the URL in a browser should show the plain spec contents and nothing else:Finish the wizard
Continue through Authentication Method and the rest of the wizard the same way you would for any other custom server. The right choice depends on how the underlying API expects to be authenticated. See Authentication Method.
Test your spec before saving
Before finishing the wizard, click Test YAML spec next to the OpenAPI YAML URL field. Airia fetches your spec, converts it exactly as it would for a real connection, and shows a preview of the tools it produces, so you can confirm everything looks right without creating the server first. If your spec is hosted somewhere that requires authentication to read (for example a private repository), you can supply a credential just for this test. It’s used once to fetch the spec and is never saved. On success, you’ll see how many tools were found, along with a preview of their names and descriptions. If the test fails, it tells you which stage it failed at:| Stage | What it means |
|---|---|
| Validation | One of the URLs you entered isn’t usable, for example it isn’t reachable or points somewhere unsafe. |
| Fetch | Airia couldn’t retrieve the spec from the OpenAPI YAML URL. A status code and a hint are included, for example an expired token or a missing permission. |
| Parse | The spec was retrieved but couldn’t be converted into tools. This usually means the file isn’t a valid OpenAPI spec. |
Privately hosted specs
If your OpenAPI spec itself lives somewhere that requires authentication to read, such as a private GitHub repository, Airia needs a credential to fetch it. Today this supports a GitHub personal access token. You’ll be prompted for this credential when you add the server to a Deployment or Gateway, on the same step where you configure other credentials. If your spec is publicly readable, skip this entirely.Custom authentication headers specifically for fetching the spec (separate from authenticating to the API itself) are coming in a future release.
Related Resources
Custom MCP Servers
Configure the full custom server wizard SpecLink runs inside
Authentication Method
Choose how Airia authenticates to the underlying API
Server Management
Approve your SpecLink server before anyone can use it
Gateway/Deployment Creation
Add the server to a Gateway or Deployment