Custom MCP Servers

Add an MCP server that isn’t in Airia’s catalogue, and configure how it connects and authenticates.

A custom MCP server is an MCP server you configure yourself, for a service that isn’t part of Airia’s built-in catalogue. Once created, it behaves like any catalogue server: it needs approval in Server Management before anyone can use it, and it can be added to Gateways and Deployments the same way.

Use a custom server when:

• The server you need isn’t in Airia’s catalogue yet.
• You can’t find a remote server anywhere, but you have an OpenAPI (Swagger) spec. See SpecLink.

Create a Custom Server

1. Start a new custom server

   Open the Custom MCP Server tool at https://airia.ai/settings/mcp-servers/new.

2. Fill in the basics

   Enter a Server Name and Category. Both are required. Description and Tags are optional. See Basic Information for what each field controls.

3. Configure the remote connection

   Choose a Transport Type (default: HTTP (MCP Protocol)), enter the server’s Server URI, and click Validate. You can’t continue without it. Add custom headers if the server requires them, and turn on Use ACC if you want to route the connection through the Airia Cloud Connector.

4. Choose an authentication method

   Pick No Authentication, API Key, OAuth 2.0 / DCR, or Pass-Through Authentication, based on how the underlying server actually authenticates. See Authentication Method below. This isn’t a free choice.

5. Save, then connect credentials

   Save the server. It’s now ready to be added to a Deployment or Gateway.

Basic Information

Field	Required	Description
Server Name	Yes	The name the MCP server will appear as when creating Deployments or Gateways.
Category	Yes	The category the server can be filtered by when creating Deployments or Gateways.
Description	No	A short description of the server’s purpose and functionality. Appears on the server card.
Tags	No	Help you organize and search for your server later on.

Remote Configuration

Transport Type

The transport type is the protocol Airia uses to communicate with the custom server. It’s a property of the underlying server itself, so choosing the wrong one will cause the server to fail.

Transport	Description
HTTP (MCP Protocol) (Default)	The current standard protocol, following spec revision 2025-03-26. All communication happens over a single endpoint; the server streams responses when needed and identifies sessions via the Mcp-Session-Id header. Use this for all new integrations, and default to it when a transport type isn’t specified in a server’s documentation.
SSE (Server Sent Events)	The original protocol for remote MCPs, from the 2024-11-05 MCP spec revision. Often used by server URLs ending in /sse, though occasionally an /sse endpoint actually expects HTTP transport. It uses two channels: the client opens a long-lived GET connection to /sse to receive server messages as Server-Sent Events, and the server tells the client a separate endpoint (usually /messages) to POST client requests to.
Hosted YAML (OpenAPI spec)	An Airia-specific transport type for services that don’t have an official remote MCP, have a poorly implemented one, or whose tools don’t cover your use case. You’ll need to provide the OpenAPI YAML URL and an Upstream API Base URL. See SpecLink for the rest of this transport’s setup.

Server URI

The HTTPS endpoint the MCP server is hosted at, for example https://mcp.slack.com/mcp.

You must click Validate before continuing to the next step.

Use ACC

Whether you want to route the server through the Airia Cloud Connector.

Custom Headers (Optional)

Some servers require additional HTTP headers to be sent with each request. You can usually find these in the documentation page for the MCP server you’re connecting to.

For example, Datadog’s documentation lists the following configuration:

{
  "mcpServers": {
    "datadog": {
      "type": "http",
      "url": "https://mcp.datadoghq.com/v1/mcp",
      "headers": {
        "DD_API_KEY": "<YOUR_API_KEY>",
        "DD_APPLICATION_KEY": "<YOUR_APPLICATION_KEY>"
      }
    }
  }
}

Here, the headers you’d need to add are DD_API_KEY and DD_APPLICATION_KEY.

Use {AuthToken} as a placeholder for credential values.

DCR OAuth servers generally don’t need custom headers.

Authentication Method

• No Authentication: Some servers, usually documentation servers, don’t require authentication to access. Since there’s no authentication, the server won’t be able to identify you as a specific user. In a server’s documentation, its configuration will often contain only a URL.
• API Key: Used for servers with API key or Bearer token authentication. Set up the headers API key auth needs in the Custom Headers section of Remote Configuration.
• OAuth 2.0 / DCR: The most common authentication method for MCP servers, and usually the one described in a server’s documentation. If a server’s configuration includes just a URL and you’d expect to have to sign in to use it, it’s most likely a DCR OAuth server. See Supported Credential Types for how DCR and manual OAuth registration differ.
• Pass-Through Authentication: Airia forwards incoming request headers directly to the remote server. This only works if the way you authenticate to Airia is identical to the way you authenticate to the remote server.

Authentication method is a property of the underlying server, so it’s usually not a free choice. If a server uses API keys for authentication, you can’t choose DCR OAuth instead. Doing so will cause the connection attempt to fail.

Related Resources

SpecLink

Turn a hosted OpenAPI spec into MCP tools without a remote MCP server

Server Management

Approve custom and catalogue servers for your organization

Gateway/Deployment Creation

Add your custom server to a Gateway or Deployment

Supported Credential Types

See how each authentication method works in more detail