MCP Protocol

Airlock implements the Model Context Protocol (MCP) for AI agent communication.

Overview

MCP is a JSON-RPC based protocol that allows AI agents to discover and call tools. Airlock exposes your API operations as MCP tools.

Endpoints

HTTP Transport

POST https://mcp.air-lock.ai/{projectId}

Used by Claude Desktop, Augment, and other MCP clients.

WebSocket Transport

wss://ws.air-lock.ai?projectId={projectId}&token={token}

For real-time bidirectional communication and instant notifications.

Authentication

Token Authentication

Include your MCP token in the Authorization header:

Authorization: Bearer {your-mcp-token}

MCP OAuth 2.0

Airlock supports the MCP OAuth 2.0 specification:

1. Discover metadata: GET /.well-known/oauth-authorization-server
2. Register client: POST /register
3. Authorize: GET /oauth/authorize
4. Token: POST /oauth/token

JSON-RPC Methods

initialize

Initialize the MCP session:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "airlock",
      "version": "1.0.0"
    }
  }
}

tools/list

List available tools:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "list_users",
        "description": "List all users",
        "inputSchema": {
          "type": "object",
          "properties": {
            "limit": {
              "type": "integer",
              "description": "Maximum results"
            }
          }
        }
      }
    ]
  }
}

tools/call

Call a tool:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_users",
    "arguments": {
      "limit": 10
    }
  }
}

Response (success):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\": 1, \"name\": \"Alice\"}, ...]"
      }
    ]
  }
}

Response (approval required):

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"status\": \"PENDING_APPROVAL\", \"requestId\": \"abc123\", \"statusUrl\": \"https://control-room.air-lock.ai/requests/abc123\", \"approvalUrl\": \"https://control-room.air-lock.ai/requests/abc123\", \"pollIntervalSeconds\": 15, \"message\": \"This operation requires approval. An approver has been notified.\"}"
      }
    ]
  }
}

TIP

The approval response contains a structured JSON object with URLs for checking status and a suggested poll interval. Use the WebSocket transport for real-time notifications instead of polling.

Tool Mapping

OpenAPI operations map to MCP tools:

OpenAPI	MCP Tool
operationId: list_users	Tool name: list_users
summary: List all users	Tool description
Request body schema	Tool inputSchema
Path parameters	Added to inputSchema.properties
Query parameters	Added to inputSchema.properties

Error Handling

Errors are returned as JSON-RPC errors:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "field": "limit",
      "reason": "must be positive integer"
    }
  }
}

Error Codes

Code	Meaning
-32700	Parse error
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error

Rate Limiting

Organizations have monthly request limits. When exceeded:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32603,
    "message": "Rate limit exceeded"
  }
}