Creating Servers

A server in Airlock represents an API you want to expose to AI agents through the MCP protocol.

Creating a Server

From the Control Room

1. Navigate to Servers in the sidebar
2. Click Create Server
3. Fill in the server details:
   • Name: A descriptive name for your server
   • OpenAPI Specification: Your API's OpenAPI/Swagger definition
   • Target URL: The base URL of your API

OpenAPI Specification

Airlock uses OpenAPI specifications to understand your API's structure:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
servers:
  - url: https://api.example.com
paths:
  /users:
    get:
      operationId: list_users
      summary: List all users
      responses:
        '200':
          description: List of users
    post:
      operationId: create_user
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                email:
                  type: string

Operation IDs

Each operation in your OpenAPI spec must have an operationId. This becomes the tool name in MCP:

• operationId: list_users becomes a tool called list_users
• operationId: create_user becomes a tool called create_user

Server Configuration

Target URL

The target URL is where Airlock sends requests. This can differ from the URL in your OpenAPI spec:

• OpenAPI servers[0].url: Documentation/design time URL
• Airlock Target URL: Runtime URL for actual requests

This allows you to:

• Use different environments (staging, production)
• Route through internal networks
• Add path prefixes

Authentication

Each user connecting to a server provides their own API credentials:

• Bearer Token: For REST APIs that use token-based authentication
• OAuth: For services like Google Calendar that support OAuth flows

See Authentication for details.

Managing Servers

Editing

Click on a server to view and edit its configuration:

• Update the OpenAPI specification
• Change the target URL
• Modify policies

Deleting

1. Click on the server to open the detail page
2. Scroll to the bottom of the page (admin access required)
3. Click the Delete Server button

WARNING

Deleting a server removes all associated policies, access tokens, and pending requests.

Best Practices

Operation Naming

Use consistent, descriptive operation IDs:

# Good
operationId: list_orders
operationId: get_order_by_id
operationId: create_order

# Avoid
operationId: op1
operationId: getOrder  # Inconsistent casing

API Versioning

Include version information in your server name or use separate servers for different API versions:

• "My API v1"
• "My API v2"

Security

• Never include credentials in the OpenAPI specification
• Use HTTPS for all target URLs
• Regularly rotate API credentials