Creating Integrations

An integration in airlock represents an API or service you want to expose to AI agents through the MCP protocol.

Integration Types

airlock supports several integration types:

There is no separate type picker: every integration starts from the one list on the Connectors page. It holds your organization's connections and the catalog together: anything that needs you comes first (a broken connection, or one a colleague already set up that you have not signed in to yet, badged Sign in), then what is connected, then what you can add. The catalog part holds airlock's own surfaces and the 250+ pre-built services. Bringing your own API or MCP server is an admin's job, from Rules → Connectors, Add a system, then Build your own. The search at the top of the page searches the whole list. Services airlock does not support yet appear with a Request badge; see Requesting an integration.

Creating an Integration

Creating integrations requires an organization admin. Members with the USER role see only the integrations an admin has given them access to. The catalog and the creation entry points are hidden for them, and the API rejects creation with Admin access required.

From the Control Room

1. Open Connectors from the left sidebar
2. Connect a pre-built integration from the list. To bring your own (admins only), open Rules → Connectors, Add a system, then Build your own and pick OpenAPI (custom REST API) or MCP Proxy (wrap an existing MCP server)
3. Follow the wizard to finish creating the integration

Who can use it?

Before the integration is created, the wizard asks Who can use it?:

• Everyone (the default): anyone in the integration's home space can use it.
• Chosen people and spaces: only the people and spaces you pick, plus any service accounts you add. Pick at least one person or space: a service account on its own narrows nothing.

The choice is saved together with the integration, and you can change it later on the integration's Access tab. See Access Control.

Pre-built Integrations

Select from 250+ pre-configured integrations. These come with tools already defined, so no OpenAPI spec is needed. See Pre-built Integrations for the full list.

A few integrations (Slack and Vercel) accept either a sign-in or an API key. For those the wizard asks How do you want to connect?: Sign in authorizes airlock with your account, and Use an API key has you paste a key under Your connection on the integration's Settings tab after it is created.

Custom OpenAPI Integration

For custom REST APIs:

1. Give the Specification URL your OpenAPI document is published at and click Fetch, or paste the document (YAML or JSON) into the box below. On the same screen, optionally set a custom auth header name if your API doesn't use a Bearer token.

   Importing from a URL is worth preferring: airlock remembers the address, so the integration can be refreshed later when the API changes. See Keeping the specification up to date. The address has to be reachable over the public internet without a key.

2. Click Analyze & Continue. airlock parses the spec and extracts the tools.

3. On the Set up the integration step, review the Name (auto-filled from the spec's title, and editable if you like) and the list of tools that will be deployed. The step sets nothing per tool: each tool's setting is set on the Rules page.

4. Click Deploy Tools to finish creating the integration.

The new integration starts on the Rules page's defaults per category: Read and Draft are Allow, and Write and Send wait for an admin's Approval. A category one of your house rules covers is proposed from that rule instead. To change any of it, open Rules → Connectors and find the integration. See Policies.

The Target URL (the base URL where airlock sends requests) is optional. See Target URL below.

MCP Proxy Integration

To put airlock's policies, approvals, and audit trail in front of an MCP server that isn't in the catalog:

1. As an admin, open Rules → Connectors, Add a system, then Build your own → MCP Proxy.
2. Give the connection a name and paste the MCP server's URL. It must be HTTPS.
3. Click Add MCP. airlock probes the server to work out how it authenticates:
   • OAuth with dynamic client registration: you're sent straight to the provider's consent screen.
   • OAuth requiring a pre-registered app: airlock asks for your own OAuth Client ID and Client Secret, then continues.
   • API key, or no auth at all: you land under Your connection on the integration's Settings tab; paste the key there and the tools sync automatically.

Extra headers. Some MCP servers need headers next to (or instead of) the API key, such as a client id. An admin adds them under Extra headers in Your connection, on the Settings tab: the admin sets the header names, and each member enters their own values, which are stored encrypted and never shown again. Calls are refused until every header has a value. When the connection is shared with your team (see Authentication below), the admin enters one set of values for everyone instead.

OpenAPI Specification

airlock accepts OpenAPI 3.0, 3.1, and 3.2, in YAML or JSON. Swagger 2.0 documents are rejected, so convert them to OpenAPI 3 first (for example in editor.swagger.io via Edit → Convert to OpenAPI 3) and paste the result. Tools are generated from get, post, put, delete, and patch operations; other methods are ignored.

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

Give every operation an operationId. It becomes the tool name agents see in MCP:

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

It is optional. An operation without one gets a name derived from its method and path (get_users_id), which is harder for an agent to interpret. Tool names are capped at 64 characters and truncated beyond that, so keep operationId values short.

airlock memory integration (Knowledge Graph)

An airlock memory integration is a per-organization knowledge graph, a store for entities and the relationships between them. It comes pre-wired with the memory_* tool family: search, get/explore entities, link/archive/delete, batch create, schema introspection, and read-only SQL queries over the graph's nodes and edges views.

To create one:

1. On the Rules page, under Connectors, open Add a system and choose airlock memory under From airlock
2. The Set up the integration step lists the memory tools and asks nothing about them: each tool's setting is set on the Rules page. Click Deploy Tools. The name is fixed to airlock memory.

The schema is layered: entities live in one of four layers (semantic, temporal, procedural, code) with conventional types like Person, Project, Document, Event, Decision, and Workflow. The schema grows on demand: when an agent writes a new PascalCase entity or relationship type, it's registered automatically. You do not need to seed types up front. Storage is backed by Parquet files on S3 and queried with DuckDB, so you do not need to run or manage any database yourself.

airlock code graph integration

An airlock code graph integration indexes one or more of your GitHub repositories and exposes them to agents as a queryable code-intelligence surface. Agents can ask questions like "which functions call chargeCustomer?", "what's the call graph for the checkout flow?", or "who depends on this module across repos?" without you writing any tools.

To create one:

1. On the Rules page, under Connectors, open Add a system and choose airlock code graph under From airlock (the name is fixed to airlock code graph)
2. On the integration's detail page, install the airlock Code GitHub App to grant read access to your repositories
3. Choose which repositories to track
4. Click the sync icon next to a repo (or Sync all) to run the first index
5. Turn on Auto-sync for each repo you want re-indexed whenever someone pushes to it. It is off by default

The first sync takes a few minutes for typical repositories; with auto-sync on, later pushes trigger incremental updates. The Repositories section on the integration's Settings tab shows sync status per repo and lets you trigger a manual re-sync at any time.

Integration Configuration

Target URL

The target URL is the base URL airlock actually sends requests to. It is optional: if you leave it unset, airlock uses the first entry in your spec's servers list.

Set one (on the integration's Settings tab under Your connection, admin only) when you want to point the integration somewhere other than what the spec says:

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

If your spec declares no servers and no target URL is set, calls will fail.

Authentication

By default each user connecting to an integration provides their own credentials:

• OAuth: For services that support OAuth flows (GitHub, Google Calendar, etc.)
• API Key / Bearer Token: For services that use static credentials

For an integration that takes an API key, an admin can instead turn on Share with your team under Your connection on the Settings tab and store one credential there. Everyone the admin grants under Who can use it then calls the service with it, without entering anything of their own and without ever seeing it. Anyone who saved their own credential keeps using theirs. Integrations that sign each person in individually (OAuth only) cannot use a shared credential.

See Authentication for details.

Syncing Tools

Sync tools on the connector's row on the Rules page refreshes the tool list of every connection of the connector, for MCP-proxy integrations (including every pre-built one) and for airlock's own built-in surfaces. Custom OpenAPI integrations have no sync button; their tools are fixed at the spec you deployed.

airlock also checks connected integrations for upstream tool changes automatically and notifies admins. See Syncing Tools for the full flow. GitHub and Box are the exceptions to the automatic check: their tools must be synced manually.

Managing Integrations

Editing

Click on an integration to view and edit its configuration:

• Rename the integration and edit its categories (Settings tab)
• Set the target URL (Settings tab, Your connection)
• Override tool descriptions (Tools tab); block tools and sync them on the connector's row on the Rules page
• Manage your own API credentials (Settings tab, Your connection)

If the integration knows the address its specification is published at, you can also refresh it in place rather than rebuilding it. See below.

Keeping the specification up to date

An API's specification changes over time: operations are added, parameters move, endpoints retire. If the integration has a Specification URL, airlock can re-read the document and bring its tools into line without you rebuilding anything.

On the integration's Settings tab, under Specification Source:

• Specification URL is the address the document is published at. You can add one to an integration created by pasting, which is what makes an older integration refreshable.
• When the specification changes decides what happens on airlock's own schedule:
  • Only refresh when I ask is the default. Nothing happens unless you press Refresh now.
  • Tell me, and wait for my approval fetches the document, tells you what it would change, and leaves the integration exactly as it is until you apply it.
  • Update this integration automatically applies the new document as soon as it changes, and tells you afterwards.
• How often to check sets the cadence, from hourly to weekly.

New operations are not simply switched on. They follow your organization's Connector tool updates rule (Rules → Connector tool updates). airlock does not check a custom API's operations, so under Available after a security scan, the default, a new operation waits for an admin: every call needs approval until an admin marks it reviewed. Under Hidden until an admin approves it it arrives hidden. Operations that disappear from the specification keep the approval settings you gave them, so one that comes back later comes back configured.

A document that airlock cannot turn into any tools at all is refused rather than applied. That is almost always a sign the address now answers with an error page or a sign-in redirect rather than the specification, and the reason is shown on the same screen.

If an integration has no specification URL, its document still cannot be replaced. Add the address, or create a new integration from the updated specification and delete the old one.

Deleting

1. Click on the integration to open the detail page
2. Open the Settings tab (admin access required)
3. In the danger zone, click the Delete MCP button

Warning: Deleting an integration 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

Security

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