Guides¶

Step-by-step instructions for common tasks.

Adding a New System¶

Systems (adapters) are created and managed through the web UI.

Using the Adapter Generator (Recommended)¶

Go to Systems → Create New System
Click Adapter Generator
Choose your source:
OpenAPI/Swagger spec — Paste a URL, Adapterly discovers all endpoints
HAR file — Record API calls in browser DevTools, upload the HAR file
Manual — Define endpoints one by one
Review the discovered endpoints and select which ones to import
Configure authentication type and credentials
Click Test Connection — the system becomes "confirmed" after first successful call

Manual Setup¶

Go to Systems → Create New System
Fill in system details (name, alias, industry)
Add an Interface (base URL, auth type)
Add Resources and Actions (endpoints)
Enable MCP for the actions you want AI agents to access

Configuring Credentials¶

Each system requires credentials configured per account.

API Key Authentication¶

Go to Systems → select system → Configure
Select auth type: API Key
Enter:
Header name (e.g., X-API-Key, Authorization)
Key value
Click Test Connection

Bearer Token Authentication¶

Select auth type: Bearer Token
Enter your pre-generated access token
Click Test Connection

OAuth 2.0¶

Select auth type: OAuth 2.0
Enter:
Token URL (e.g., https://api.example.com/oauth/token)
Username / Client ID
Password / Client Secret
Adapterly automatically obtains, caches, and refreshes tokens
Click Test Connection

DRF Token Authentication¶

Select auth type: DRF Token
Enter username and password
Adapterly obtains and caches the token automatically

Basic Authentication¶

Select auth type: Basic
Enter username and password
Credentials are Base64-encoded automatically

Setting Up a Project¶

Projects scope which systems and tools are available to AI agents.

Creating a Project¶

Go to Projects → Create New
Enter project name and optional description
Save the project

Adding Integrations¶

Open the project
Click Add Integration
Select the system to include
Repeat for each system this project needs

Restricting Tool Categories¶

Open the project settings
Under Allowed Categories, select which categories are permitted
Tools outside these categories will be blocked for this project

Creating and Managing API Keys¶

Create an API Key¶

Go to MCP Gateway → API Keys
Click Create API Key
Configure:
Name - Descriptive name (e.g., "Claude - E18 Project")
Mode - Safe (read-only) or Power (read/write)
Project (optional) - Bind to a specific project
Agent Profile (optional) - Apply a permission profile
Copy the key (ak_live_xxx) - shown only once

Manage Keys¶

Revoke: Immediately disables the key
Rotate: Create a new key and revoke the old one
Keys are visible in MCP Gateway → API Keys

Deploying a Standalone Gateway¶

For on-premise or edge deployments, run Adapterly as a standalone Docker gateway.

Prerequisites¶

Docker and Docker Compose installed
Network access to the control plane (adapterly.ai) for initial sync

Setup¶

Clone the gateway package: bash cd /opt/adapterly/adapterly-gateway docker compose up -d
Open the Setup Wizard at http://your-host:8080/setup/
Register with the control plane:
Enter your control plane URL
Authenticate with your account credentials
The gateway syncs adapter specs and API keys
Configure credentials:
Enter system credentials directly in the gateway admin UI
Credentials never leave the gateway
Point AI agents to the gateway's MCP endpoint: http://your-host:8080/mcp/v1/