> ## Documentation Index
> Fetch the complete documentation index at: https://explore.airia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SpecLink
> Turn a hosted OpenAPI (Swagger) spec into MCP tools without building a custom MCP server.
SpecLink reads a hosted OpenAPI (Swagger) specification and generates a working set of MCP tools from it, one tool per operation the spec defines. Nobody has to write or maintain a custom MCP server.
Use SpecLink when a service you rely on publishes an OpenAPI spec but doesn't ship a remote MCP server of its own. It's a transport option inside the Custom MCP Server tool, so it plugs into the same approval, Deployment, and Gateway flow as every other server. See [Custom MCP Servers](/mcps/admin-controls/custom-mcp-servers) for the full wizard; this page covers only what's different when you choose SpecLink.
## 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
Begin a new custom server and fill in the **Basic Information** step as usual.
On the **Remote Configuration** step, set **Transport Type** to **Hosted YAML (OpenAPI spec)**.
| 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:
This URL is only used to fetch the spec itself. All of the tools SpecLink generates send their actual requests to the Upstream API Base URL.
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](/mcps/admin-controls/custom-mcp-servers#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.
This credential only reads the spec file. It's separate from how the underlying API itself is authenticated, which you set up through the custom server's normal **Authentication Method**.
Custom authentication headers specifically for fetching the spec (separate from authenticating to the API itself) are coming in a future release.
## Related Resources
Configure the full custom server wizard SpecLink runs inside
Choose how Airia authenticates to the underlying API
Approve your SpecLink server before anyone can use it
Add the server to a Gateway or Deployment