# Adapterly Documentation (English)

Downloaded from https://adapterly.ai/help/en/

============================================================


# Adapterly Documentation

Welcome to Adapterly - the MCP gateway that connects AI agents to your business systems.

> **New to Adapterly?** Start with the [Getting Started Tutorial](/help/en/tutorial/) for a complete introduction.

## Who is Adapterly for?

- **Teams using AI agents** - Give Claude, ChatGPT, or Cursor access to your business systems
- **System integrators** - Connect APIs and expose them as MCP tools
- **Enterprises** - Centralize system access with audit logging and project scoping

## Quick Start

1. **Add systems** — Create adapters from OpenAPI specs, HAR files, or configure manually
2. **Configure credentials** - Set up OAuth, API keys, or other auth for each system
3. **Create a project** - Scope which systems and tools are available
4. **Generate API key** - Get an `ak_live_xxx` key for MCP access
5. **Connect AI agent** - Point Claude or any MCP client to the gateway

## Concepts at a Glance

| Concept | Description |
|---------|-------------|
| **System** | External service (any REST or GraphQL API) |
| **Interface** | System's API endpoint (REST, GraphQL, XHR) |
| **Resource** | Data entity (projects, users, orders) |
| **Action** | Operation on resource (list, get, create, update) |
| **Project** | Scoped workspace with selected system integrations |
| **API Key** | MCP authentication key (`ak_live_xxx` / `ak_test_xxx`) |
| **MCP Tool** | Auto-generated function for AI agents |

## Documentation Structure

### [Core Concepts](/help/en/concepts/)
Deep dive into systems, projects, permissions, and gateway architecture.

### [Guides](/help/en/guides/)
Step-by-step instructions for adding adapters, configuring credentials, and deploying gateways.

### [Recipes](/help/en/recipes/)
MCP usage examples and AI conversation patterns.

### [MCP & Agents](/help/en/mcp/)
MCP protocol details, connection setup, and agent configuration.

### [Reference](/help/en/reference/)
Adapter data model, MCP JSON-RPC protocol, and API endpoints.

### [Troubleshooting](/help/en/troubleshooting/)
Common errors and their solutions.

---



------------------------------------------------------------


# Core Concepts

This page covers Adapterly's core concepts in depth.

## Systems

A system represents an external service that Adapterly connects to. The hierarchy is:

```
System
  └── Interface (API endpoint)
        └── Resource (data entity)
              └── Action (operation)
```

**Example:**
```
My System
  └── REST API
        └── projects
              ├── list
              ├── get
              └── create
```

### Interface

An interface defines the API basics:
- **Base URL** - API root address
- **Authentication** - How to authenticate
- **Rate limit** - Request limits

### Resource

A resource is an API data entity, such as `projects`, `users`, or `orders`.

### Action

An action is an operation on a resource:
- `list` - List all
- `get` - Get single
- `create` - Create new
- `update` - Update
- `delete` - Delete

Each action with `is_mcp_enabled = true` becomes an MCP tool.

---

## Projects and Project Integrations

### Projects

A **Project** is a scoped workspace that controls which systems and tools are available to AI agents.

- Projects belong to an Account
- Each project has a name, slug, and optional description
- API keys can be bound to a specific project

### Project Integrations

A **ProjectIntegration** links a system to a project:

- Controls which systems are accessible within a project
- Each integration references a specific System
- AI agents with a project-scoped API key can only access systems linked via ProjectIntegration

**Example:**
```
"My Project"
  ├── ProjectIntegration → System A
  ├── ProjectIntegration → System B
  └── ProjectIntegration → Google Sheets
```

---

## API Keys and Modes

### API Keys

MCP API keys authenticate AI agents. Key format: `ak_live_xxx` (production) or `ak_test_xxx` (test).

Each key has:
- **Mode** - Safe (read-only) or Power (read/write)
- **Project** (optional) - Restricts access to a specific project's systems
- **Agent Profile** (optional) - Applies a reusable permission profile
- **is_admin** - Can switch projects via header

### Modes

| Mode | Description |
|------|-------------|
| **Safe** (default) | Only read actions (list, get) are allowed |
| **Power** | All actions allowed (list, get, create, update, delete) |

---

## Permissions and Access Control

### Permission Layers

Access is controlled at multiple levels, intersected together:

```
Effective permissions = Agent policies ∩ Project policies ∩ User policies
```

### Tool Categories

Tools are organized into categories (e.g., `construction.read`, `logistics.write`). Categories are mapped to tools via fnmatch patterns in `ToolCategoryMapping`.

### Agent Profiles

Reusable permission profiles that can be attached to API keys:
- **allowed_categories** - Which tool categories are permitted
- **include_tools** - Explicitly included tools (override categories)
- **exclude_tools** - Explicitly excluded tools
- **mode** - Safe or Power

### User Roles

| Role | Permissions |
|------|-------------|
| **Admin** | Full access: systems, projects, API keys, user management |
| **User** | View projects and systems assigned to them |

---

## Audit Logging

### What is Logged

Every MCP tool call is recorded in the audit log with:
- Timestamp
- API key used
- Tool name and parameters
- Response status and data
- Duration
- Account and project context

### Viewing Logs

- **UI**: MCP Gateway → Audit Log
- **API**: `GET /api/mcp/audit-logs/`

---

## Gateway Architecture

Adapterly supports two deployment modes:

### Monolith (Default)

Everything runs on a single server:
- Django handles UI and REST API
- FastAPI handles MCP protocol (Streamable HTTP)
- PostgreSQL stores all data

### Control Plane + Gateway

For distributed or on-premise deployments:

**Control Plane** (Django at adapterly.ai):
- Manages accounts, systems, adapter definitions
- Provides Gateway Sync API for gateways to pull configuration

**Gateway** (standalone FastAPI + SQLite):
- Runs independently (e.g., on-premise, Docker)
- Syncs adapter specs and API keys from control plane
- Credentials stay on the gateway (never sent to control plane)
- Provides MCP endpoint for AI agents

The `gateway_core` shared package contains executor, crypto, models, auth, and diagnostics code used by both deployment modes.



------------------------------------------------------------


# Frequently Asked Questions

## General

### What is Adapterly?
Adapterly is an MCP (Model Context Protocol) gateway that connects AI agents to external business systems. Create adapters for any REST or GraphQL API through the web UI, and let AI agents like Claude, ChatGPT, and Cursor query and manage your data.

### Who is Adapterly for?
- Teams using AI agents who need access to business systems
- System integrators connecting multiple APIs
- Enterprises managing data across platforms with audit and access control
- Construction, logistics, and ERP professionals

### How is Adapterly different from a regular API gateway?
Adapterly speaks the MCP protocol natively. AI agents can discover available tools, understand their parameters, and call them directly. No custom integration code needed - just connect your systems and give the agent an API key.

## Systems

### How do I connect a new system?
1. Go to **Systems** → **Create New System** or select an existing one
2. Use the **Adapter Generator** to import from OpenAPI specs, HAR files, or configure manually
3. Go to **Configure** and enter credentials (API key, OAuth, etc.)
4. Click **Test Connection** — the system becomes "confirmed" after first successful call

### What authentication methods are supported?
- OAuth 2.0 (password grant, client credentials)
- API Key (custom header)
- Bearer Token
- Basic Authentication
- DRF Token (username/password → auto-generated token)
- Session/Cookie (XHR for web apps)

### Why does my connection test fail?
Common causes:
- Incorrect credentials (wrong key, expired token)
- API endpoint is down or unreachable
- Network/firewall restrictions
- Rate limiting from the external API

Check the error message for specific details.

### Can I add a custom system?
Yes! Use the **Adapter Generator** to create adapters from OpenAPI specs, HAR files, or configure endpoints manually through the web UI. See the [Guides](/help/en/guides/) for details.

## MCP & AI Agents

### What is MCP?
Model Context Protocol (MCP) is a standard for AI assistants to use external tools. Adapterly acts as an MCP server, giving AI agents access to your connected systems via Streamable HTTP (JSON-RPC 2.0).

### Which AI agents work with Adapterly?
Any MCP-compatible client, including:
- Claude (Desktop and Code)
- ChatGPT (with MCP support)
- Cursor
- Custom agents using MCP libraries

### How do I connect Claude to Adapterly?
1. Generate an API key in MCP Gateway → API Keys
2. Add to your Claude configuration:
   ```json
   {
     "mcpServers": {
       "adapterly": {
         "url": "https://adapterly.ai/mcp/v1/",
         "headers": {
           "Authorization": "Bearer ak_live_xxx"
         }
       }
     }
   }
   ```
3. Ask Claude: "What Adapterly tools do you have?"

### What's the difference between Safe and Power mode?
- **Safe mode** (default): Read-only - agents can list and get data but can't create, update, or delete
- **Power mode**: Full access - agents can perform all operations including writes

### Is my data safe with AI access?
- All MCP calls are authenticated via API keys
- Access is controlled by mode, Agent Profile, and project scoping
- Every tool call is logged in the audit log with full details
- You can revoke API keys instantly
- Credentials are stored encrypted

### What can AI agents do vs. what requires manual setup?
AI agents can:
- Read data from configured systems
- Create/update/delete data (with Power mode)
- Query across multiple systems

AI agents cannot:
- Configure new systems or credentials
- Manage API keys or permissions
- Access systems without configured credentials

## Projects

### What are Projects?
Projects are scoped workspaces that control which systems are available to AI agents. Each project has its own set of system integrations and access policies.

### Do I need to create a project?
Projects are optional. If your API key isn't bound to a project, the agent can access all systems in your account. Projects are useful for:
- Restricting access to specific systems per use case
- Organizing integrations by business context
- Applying different permission policies

## Gateway Deployment

### Can I run Adapterly on my own server?
Yes. Adapterly supports a standalone gateway mode (Docker) that runs on your infrastructure. The gateway syncs adapter definitions from the control plane but keeps credentials locally.

### What's the difference between monolith and gateway mode?
- **Monolith**: Everything on one server (Django + FastAPI + PostgreSQL)
- **Control Plane + Gateway**: Central management at adapterly.ai, with standalone gateways on your servers. Credentials stay on the gateway.

### How do I deploy a standalone gateway?
1. Run `docker compose up -d` in the `adapterly-gateway/` directory
2. Open the Setup Wizard at `http://your-host:8080/setup/`
3. Register with the control plane and configure credentials
4. Point your AI agents to `http://your-host:8080/mcp/v1/`

## Account & Team

### How do I add team members?
Go to **Account Settings** → **Invite User** and enter their email address.

### What permissions can team members have?
- **Admin** - Full access including system configuration and API key management
- **User** - View projects and use assigned integrations

## Getting Help

### Where can I report bugs?
Contact support through the application or email support@adapterly.ai.

### Can I request new features or adapters?
Yes! Submit feature requests through the support channel or contribute directly on GitHub.



------------------------------------------------------------


# 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)

1. Go to **Systems** → **Create New System**
2. Click **Adapter Generator**
3. 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
4. Review the discovered endpoints and select which ones to import
5. Configure authentication type and credentials
6. Click **Test Connection** — the system becomes "confirmed" after first successful call

### Manual Setup

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

---

## Configuring Credentials

Each system requires credentials configured per account.

### API Key Authentication

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

### Bearer Token Authentication

1. Select auth type: **Bearer Token**
2. Enter your pre-generated access token
3. Click **Test Connection**

### OAuth 2.0

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

### DRF Token Authentication

1. Select auth type: **DRF Token**
2. Enter **username** and **password**
3. Adapterly obtains and caches the token automatically

### Basic Authentication

1. Select auth type: **Basic**
2. Enter **username** and **password**
3. Credentials are Base64-encoded automatically

---

## Setting Up a Project

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

### Creating a Project

1. Go to **Projects** → **Create New**
2. Enter project name and optional description
3. Save the project

### Adding Integrations

1. Open the project
2. Click **Add Integration**
3. Select the system to include
4. Repeat for each system this project needs

### Restricting Tool Categories

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

---

## Creating and Managing API Keys

### Create an API Key

1. Go to **MCP Gateway** → **API Keys**
2. Click **Create API Key**
3. 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
4. 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

1. Clone the gateway package:
   ```bash
   cd /opt/adapterly/adapterly-gateway
   docker compose up -d
   ```

2. Open the Setup Wizard at `http://your-host:8080/setup/`

3. Register with the control plane:
   - Enter your control plane URL
   - Authenticate with your account credentials
   - The gateway syncs adapter specs and API keys

4. Configure credentials:
   - Enter system credentials directly in the gateway admin UI
   - Credentials never leave the gateway

5. Point AI agents to the gateway's MCP endpoint:
   ```
   http://your-host:8080/mcp/v1/
   ```

---

## Testing Connections

### Connection Test

1. Go to **Systems** → select your system → **Configure**
2. Enter credentials
3. Click **Test Connection**
4. Green checkmark = success, system becomes "confirmed"

### Testing via MCP

1. Connect an AI agent with your API key
2. Ask: "List all tools" or "List projects from [system]"
3. Verify data is returned correctly



------------------------------------------------------------


# MCP Integration

Adapterly acts as an MCP (Model Context Protocol) server, giving AI agents access to your connected business systems as callable tools.

## What is MCP?

The Model Context Protocol (MCP) is a standard that allows AI assistants like Claude, ChatGPT, and Cursor to use external tools. Adapterly implements MCP via Streamable HTTP (JSON-RPC 2.0).

## How It Works

```
AI Agent (Claude, ChatGPT, etc.)
    | (MCP JSON-RPC 2.0)
    v
Adapterly MCP Gateway
    | (authenticated API calls)
    v
External Systems (any REST/GraphQL API)
```

1. AI agent connects to Adapterly's MCP endpoint
2. Agent discovers available tools via `tools/list`
3. Agent calls tools via `tools/call`
4. Adapterly authenticates, calls the external API, and returns results
5. Every call is logged in the audit log

## Available Tools

### System Tools (Auto-generated)

For each configured system, Adapterly generates MCP tools:

```
{system}_{resource}_{action}
```

**Example tools:**
- `my_system_projects_list` — List all projects
- `my_system_projects_get` — Get project details
- `my_system_items_create` — Create items
- `my_system_reports_get` — Get reports

### Management Tools

Account and session management (available based on API key permissions):

| Tool | Type | Description |
|------|------|-------------|
| `account_get` | read | Get account details |
| `admin_session_create` | write | Create federated login session |

## MCP Modes

### Safe Mode (Default)

- Read operations allowed (list, get)
- Write operations blocked (create, update, delete)

### Power Mode

- All operations allowed
- Required for write operations
- Enable via API key settings or Agent Profile

## Setting Up MCP

### 1. Generate API Key

1. Go to **MCP Gateway** → **API Keys**
2. Click **Create API Key**
3. Select an Agent Profile (optional) or set mode manually
4. Copy the key (`ak_live_xxx`) - it won't be shown again

### 2. Connection Options

#### Option A: Streamable HTTP (Recommended)

MCP Streamable HTTP - single endpoint for all JSON-RPC communication:

```
Endpoint: https://adapterly.ai/mcp/v1/
```

**Methods:**
- `POST /mcp/v1/` - Send JSON-RPC message(s)
- `GET /mcp/v1/` - Open SSE stream for server notifications (optional)
- `DELETE /mcp/v1/` - Close session

**Headers:**
- `Authorization: Bearer <api_key>`
- `Content-Type: application/json`
- `Accept: application/json` or `text/event-stream`
- `Mcp-Session-Id: <session_id>` (returned by server, use for subsequent requests)

**Example:**
```javascript
// Send JSON-RPC message
const response = await fetch('https://adapterly.ai/mcp/v1/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ak_live_xxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list',
    params: {}
  })
});

// Get session ID from response header
const sessionId = response.headers.get('Mcp-Session-Id');
const result = await response.json();

// Use session ID for subsequent requests
const response2 = await fetch('https://adapterly.ai/mcp/v1/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ak_live_xxx',
    'Content-Type': 'application/json',
    'Mcp-Session-Id': sessionId
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 2,
    method: 'tools/call',
    params: { name: 'my_system_projects_list', arguments: {} }
  })
});
```

#### Option B: Claude Desktop / Claude Code

Configure your MCP client to connect via Streamable HTTP:

**Claude Desktop** (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "adapterly": {
      "url": "https://adapterly.ai/mcp/v1/",
      "headers": {
        "Authorization": "Bearer ak_live_xxx"
      }
    }
  }
}
```

**Claude Code** (`.claude/settings.json`):
```json
{
  "mcpServers": {
    "adapterly": {
      "type": "url",
      "url": "https://adapterly.ai/mcp/v1/",
      "headers": {
        "Authorization": "Bearer ak_live_xxx"
      }
    }
  }
}
```

#### Option C: Standalone Gateway

For on-premise deployments, connect to a local gateway instance:

```json
{
  "mcpServers": {
    "adapterly": {
      "url": "http://localhost:8080/mcp/v1/",
      "headers": {
        "Authorization": "Bearer ak_live_xxx"
      }
    }
  }
}
```

### 3. Verify Connection

Ask your AI agent:
> "What Adapterly tools do you have access to?"

The agent should list all available system tools.

## Tool Parameters

Each tool has specific parameters based on its action:

### List Actions
```json
{
  "page": 1,
  "pageSize": 100,
  "fetch_all_pages": true
}
```

### Get Actions
```json
{
  "id": "project-uuid-here"
}
```

### Create Actions
```json
{
  "data": {
    "name": "New Project",
    "description": "Project description"
  }
}
```

## Pagination

For list endpoints with many items, Adapterly handles pagination automatically:

```
User: "Get all items from the project"

AI calls: my_system_items_list(
    project_id="...",
    fetch_all_pages=true
)
```

**Safety limits:**
- Maximum 100 pages
- Maximum 10,000 items
- 2-minute timeout
- Stops on empty or duplicate pages

## Error Handling

When an MCP tool fails, the agent receives error details:

```json
{
  "error": true,
  "message": "Authentication failed",
  "details": "Token expired or invalid"
}
```

The agent will typically:
1. Explain the error to the user
2. Suggest remediation steps
3. Retry if appropriate

## Best Practices

### 1. Be Specific in Requests
Instead of "get project data", say "list all active projects from System X".

### 2. Provide Context
Give the agent the information it needs:
> "Using project ID abc123, create a logpoint at coordinates 60.17, 24.94"

### 3. Review Before Writing
Ask the agent to show you what it will create before actually creating it:
> "Show me the logpoint data you would create, but don't create it yet"

## Security

### API Key Permissions
API keys are scoped by mode (safe/power), project, and Agent Profile. Use the minimum access needed.

### Audit Trail
All MCP tool calls are logged and visible in MCP Gateway → Audit Log.

### Rate Limiting
MCP calls are subject to the same rate limits as direct API access.



------------------------------------------------------------


# Recipes

Ready-to-use MCP usage examples and AI conversation patterns.

## Listing and Filtering Data

### List All Records

```
User: "Show me all my projects"

AI calls: my_system_projects_list()

AI: "Here are your projects:
    1. Project Alpha (active)
    2. Project Beta (active)
    3. Project Gamma (archived)"
```

### Filter by Criteria

```
User: "Show me only active projects created this year"

AI calls: my_system_projects_list()
AI: [filters results by date and status]

AI: "Found 3 active projects created in 2026:
    1. Project Alpha (started Jan 15)
    2. Project Beta (started Feb 3)
    3. Project Gamma (started Mar 1)"
```

---

## Cross-System Queries

### Combine Data from Multiple Systems

```
User: "Compare the project list from System A with data from System B"

AI calls: system_a_projects_list()
AI calls: system_b_items_list(project_id="...")

AI: "Here's a summary:
    - Project Alpha: 5 open items (2 critical)
    - Project Beta: 12 items (all resolved)
    - Project Gamma: 3 open items"
```

---

## Creating and Updating Records

### Create a New Record

```
User: "Create a new item in the Alpha project with coordinates 60.17, 24.94"

AI calls: my_system_items_create(
    project_id="abc-123",
    coordinates=[60.17, 24.94],
    description="New survey point"
)

AI: "Created item at 60.17, 24.94 in Project Alpha.
    ID: item-456-789"
```

### Update Existing Data

```
User: "Update the description of item ITEM-123 to 'Resolved — issue fixed'"

AI calls: my_system_items_update(
    id="ITEM-123",
    description="Resolved — issue fixed"
)

AI: "Updated item ITEM-123 with new description."
```

> **Note:** Create and update operations require **Power mode** on your API key.

---

## Using Safe vs Power Mode

### Safe Mode (Read-Only)

Safe mode is the default. Agents can only read data:

```
User: "List all items"
AI calls: my_system_items_list()  ← Allowed

User: "Create a new item"
AI calls: my_system_items_create(...)  ← Blocked
AI: "I can't create items — my API key is in Safe mode.
    Ask your admin to switch to Power mode if you need write access."
```

### Power Mode (Full Access)

Power mode enables both read and write operations:

```
User: "Create a shipment"
AI calls: my_system_shipments_create(
    sender={...},
    receiver={...},
    packages=[{weight: 5.2, dimensions: "30x20x15"}]
)

AI: "Shipment created successfully. Tracking number: SH-2026-12345"
```

---

## Project-Scoped Access

### Working Within a Project

When your API key is bound to a project, only that project's systems are available:

```
User: "What tools do you have?"

AI: "I have access to tools for the Alpha project:
    - system_a_projects_list, system_a_projects_get
    - system_b_items_list, system_b_items_get
    - google_sheets_sheets_update"
```

### Listing Available Systems

```
User: "Which systems can I query?"

AI: "Based on my API key, I can access:
    1. System A — projects, items, reports
    2. System B — observations, inspections
    3. Google Sheets — spreadsheet data"
```

---

## Pagination and Large Datasets

### Fetching All Pages

```
User: "Get all items from the project — there might be thousands"

AI calls: my_system_items_list(
    project_id="abc-123",
    fetch_all_pages=true
)

AI: "Retrieved 2,847 items across 29 pages.
    Here's a summary by type:
    - Type A: 1,200
    - Type B: 1,647"
```

### Safety Limits

Automatic pagination has built-in safety limits:
- Maximum 100 pages per request
- Maximum 10,000 items
- 2-minute timeout
- Stops on empty or duplicate pages

---

## Audit and Monitoring

### Checking Recent Activity

```
User: "What API calls were made in the last hour?"

[Admin checks MCP Gateway → Audit Log in the UI]

Recent calls:
- my_system_projects_list (safe) — 200 OK — 12:05
- my_system_items_list (safe) — 200 OK — 12:08
- my_system_orders_create (power) — 201 Created — 12:15
```



------------------------------------------------------------


# Reference

Official Adapterly technical reference documentation.

## Adapter Data Model

Adapters are stored in the database and managed through the web UI or Adapter Generator.

### System

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name |
| `alias` | string | URL-safe identifier used in tool names |
| `mcp_prefix` | string | Optional short prefix for tool names (falls back to alias) |
| `industry` | string | Category: construction, logistics, erp, general |
| `website` | string | System's website URL |
| `description` | string | Brief description |
| `confirmation_status` | string | "unconfirmed" (default) or "confirmed" |

### Interface

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name (e.g., "REST API") |
| `alias` | string | Identifier (e.g., "api") |
| `base_url` | string | API root URL |
| `auth_type` | string | api_key, bearer, oauth2_password, basic, drf_token, xhr |
| `rate_limit` | integer | Requests per minute (optional) |

### Resource

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name (e.g., "Projects") |
| `alias` | string | Identifier used in tool names (e.g., "projects") |
| `description` | string | Brief description |

### Action

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name (e.g., "List Projects") |
| `alias` | string | Identifier (e.g., "list") |
| `method` | string | HTTP method: GET, POST, PUT, PATCH, DELETE |
| `path` | string | URL path (e.g., "/projects") |
| `is_mcp_enabled` | boolean | true = exposed as MCP tool |
| `mcp_mode` | string | "safe" (read) or "power" (write) |
| `description` | string | Tool description shown to AI agents |
| `parameters_schema` | JSON | JSON Schema for tool input parameters |
| `output_schema` | JSON | JSON Schema for tool output (optional) |

### Tool Name Generation

```
{mcp_prefix or alias}_{resource_alias}_{action_alias}
```

Example: System with alias `example` generates tools like `example_items_list` (safe) and `example_items_create` (power).

---

## MCP JSON-RPC 2.0 Protocol

Adapterly implements the MCP specification via Streamable HTTP.

### Endpoint

```
POST https://adapterly.ai/mcp/v1/
```

### Authentication

```
Authorization: Bearer ak_live_xxx
```

### Methods

| Method | Description |
|--------|-------------|
| `initialize` | Initialize MCP session, receive capabilities |
| `tools/list` | List all available tools |
| `tools/call` | Call a specific tool |
| `ping` | Health check |

### Initialize

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

### Tools List

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

Response:
```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "my_system_projects_list",
        "description": "List all projects",
        "inputSchema": {
          "type": "object",
          "properties": {
            "page": {"type": "integer"},
            "pageSize": {"type": "integer"}
          }
        }
      }
    ]
  }
}
```

### Tools Call

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "my_system_projects_list",
    "arguments": {
      "page": 1,
      "pageSize": 50
    }
  }
}
```

Response:
```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"data\": [...], \"meta\": {\"count\": 5}}"
      }
    ]
  }
}
```

---

## HTTP Endpoints

### MCP Streamable HTTP

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/mcp/v1/` | Send JSON-RPC message(s) |
| `GET` | `/mcp/v1/` | Open SSE stream for notifications |
| `DELETE` | `/mcp/v1/` | Close session |

### REST API

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/systems/` | List systems |
| `GET` | `/api/systems/{id}/` | Get system details |
| `POST` | `/api/systems/{id}/test/` | Test system connection |
| `GET` | `/api/mcp/api-keys/` | List API keys |
| `POST` | `/api/mcp/api-keys/` | Create API key |
| `GET` | `/api/mcp/audit-logs/` | List audit logs |
| `GET` | `/api/mcp/agent-profiles/` | List agent profiles |

### Gateway Sync API

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/gateway-sync/v1/register` | Register a gateway |
| `GET` | `/gateway-sync/v1/specs` | Sync adapter specs |
| `GET` | `/gateway-sync/v1/keys` | Sync API keys |
| `POST` | `/gateway-sync/v1/audit` | Push audit logs |
| `POST` | `/gateway-sync/v1/health` | Push health status |

---

## Error Codes

### MCP JSON-RPC Errors

| Code | Name | Description |
|------|------|-------------|
| `-32700` | Parse error | Invalid JSON |
| `-32600` | Invalid request | Missing required fields |
| `-32601` | Method not found | Unknown MCP method |
| `-32602` | Invalid params | Wrong parameter types or missing required params |
| `-32603` | Internal error | Server error during tool execution |

### HTTP Status Codes

| Code | Meaning | Action |
|------|---------|--------|
| `400` | Bad request | Check parameters |
| `401` | Unauthorized | Check API key |
| `403` | Forbidden | Check permissions / mode |
| `404` | Not found | Check resource ID/path |
| `429` | Rate limit | Wait and retry |
| `500` | Server error | Retry later |



------------------------------------------------------------


# Core Concepts

This page covers Adapterly's core concepts in depth.

## Systems

A system represents an external service that Adapterly connects to. The hierarchy is:

```
System
  └── Interface (API endpoint)
        └── Resource (data entity)
              └── Action (operation)
```

**Example:**
```
My System
  └── REST API
        └── projects
              ├── list
              ├── get
              └── create
```

### Interface

An interface defines the API basics:
- **Base URL** - API root address
- **Authentication** - How to authenticate
- **Rate limit** - Request limits

### Resource

A resource is an API data entity, such as `projects`, `users`, or `orders`.

### Action

An action is an operation on a resource:
- `list` - List all
- `get` - Get single
- `create` - Create new
- `update` - Update
- `delete` - Delete

Each action with `is_mcp_enabled = true` becomes an MCP tool.

---

## Projects and Project Integrations

### Projects

A **Project** is a scoped workspace that controls which systems and tools are available to AI agents.

- Projects belong to an Account
- Each project has a name, slug, and optional description
- API keys can be bound to a specific project

### Project Integrations

A **ProjectIntegration** links a system to a project:

- Controls which systems are accessible within a project
- Each integration references a specific System
- AI agents with a project-scoped API key can only access systems linked via ProjectIntegration

**Example:**
```
"My Project"
  ├── ProjectIntegration → System A
  ├── ProjectIntegration → System B
  └── ProjectIntegration → Google Sheets
```

---

## API Keys and Modes

### API Keys

MCP API keys authenticate AI agents. Key format: `ak_live_xxx` (production) or `ak_test_xxx` (test).

Each key has:
- **Mode** - Safe (read-only) or Power (read/write)
- **Project** (optional) - Restricts access to a specific project's systems
- **Agent Profile** (optional) - Applies a reusable permission profile
- **is_admin** - Can switch projects via header

### Modes

| Mode | Description |
|------|-------------|
| **Safe** (default) | Only read actions (list, get) are allowed |
| **Power** | All actions allowed (list, get, create, update, delete) |

---

## Permissions and Access Control

### Permission Layers

Access is controlled at multiple levels, intersected together:

```
Effective permissions = Agent policies ∩ Project policies ∩ User policies
```

### Tool Categories

Tools are organized into categories (e.g., `construction.read`, `logistics.write`). Categories are mapped to tools via fnmatch patterns in `ToolCategoryMapping`.

### Agent Profiles

Reusable permission profiles that can be attached to API keys:
- **allowed_categories** - Which tool categories are permitted
- **include_tools** - Explicitly included tools (override categories)
- **exclude_tools** - Explicitly excluded tools
- **mode** - Safe or Power

### User Roles

| Role | Permissions |
|------|-------------|
| **Admin** | Full access: systems, projects, API keys, user management |
| **User** | View projects and systems assigned to them |

---

## Audit Logging

### What is Logged

Every MCP tool call is recorded in the audit log with:
- Timestamp
- API key used
- Tool name and parameters
- Response status and data
- Duration
- Account and project context

### Viewing Logs

- **UI**: MCP Gateway → Audit Log
- **API**: `GET /api/mcp/audit-logs/`

---

## Gateway Architecture

Adapterly supports two deployment modes:

### Monolith (Default)

Everything runs on a single server:
- Django handles UI and REST API
- FastAPI handles MCP protocol (Streamable HTTP)
- PostgreSQL stores all data

### Control Plane + Gateway

For distributed or on-premise deployments:

**Control Plane** (Django at adapterly.ai):
- Manages accounts, systems, adapter definitions
- Provides Gateway Sync API for gateways to pull configuration

**Gateway** (standalone FastAPI + SQLite):
- Runs independently (e.g., on-premise, Docker)
- Syncs adapter specs and API keys from control plane
- Credentials stay on the gateway (never sent to control plane)
- Provides MCP endpoint for AI agents

The `gateway_core` shared package contains executor, crypto, models, auth, and diagnostics code used by both deployment modes.



------------------------------------------------------------


# Troubleshooting

Common errors and their solutions.

## MCP Connection Errors

### "Tool not found"

**Cause:** MCP tool not registered or no permissions.

**Fix:**
1. Check that the system is configured in Adapterly
2. Verify the system has resources with `is_mcp_enabled: true`
3. Check that the system is included in the project's integrations
4. Verify the API key has access (check mode and Agent Profile)
5. Restart your AI agent / MCP client to refresh the tool list

### "Authentication failed" (401)

**Cause:** Invalid or expired API key.

**Fix:**
1. Verify your API key starts with `ak_live_` or `ak_test_`
2. Check the key hasn't been revoked in MCP Gateway → API Keys
3. Ensure the `Authorization: Bearer` header is correctly set
4. Generate a new key if needed

### "Permission denied" (403)

**Cause:** API key doesn't have permission for this operation.

**Fix:**
1. Check the API key **mode**: Safe mode blocks write operations
2. Check the **Agent Profile** attached to the key
3. Check **Project policies** if the key is project-scoped
4. Switch to Power mode for create/update/delete operations

### "System credentials not configured"

**Cause:** No credentials set for the target system in this account.

**Fix:**
1. Go to **Systems** → select the system → **Configure**
2. Enter credentials (API key, OAuth, Bearer token, etc.)
3. Click **Test Connection** to verify
4. The system becomes "confirmed" after first successful call

---

## External API Errors

### "Timeout"

**Cause:** External API not responding in time.

**Fix:**
1. Check the target API's status page
2. Try a smaller request (reduce `pageSize`, don't use `fetch_all_pages`)
3. Check network connectivity
4. Retry after a brief wait

### "Rate limit exceeded" (429)

**Cause:** Too many requests to external API in short time.

**Fix:**
1. Wait before retrying
2. Reduce request frequency
3. Use pagination with smaller page sizes

### External API returns error (400, 404, 500)

**Cause:** Issue with the request parameters or the external service.

**Fix:**
1. Check the error message in the MCP tool response
2. Verify the parameters (IDs, formats) are correct
3. Check if the external API has changed (new version, deprecated endpoints)
4. View details in MCP Gateway → Audit Log

---

## MCP JSON-RPC Errors

| Code | Name | Cause | Fix |
|------|------|-------|-----|
| `-32700` | Parse error | Invalid JSON in request | Check JSON syntax |
| `-32600` | Invalid request | Missing `jsonrpc`, `method`, or `id` | Include all required fields |
| `-32601` | Method not found | Unknown MCP method | Use: `initialize`, `tools/list`, `tools/call`, `ping` |
| `-32602` | Invalid params | Wrong parameter types | Check tool's `inputSchema` |
| `-32603` | Internal error | Server error during execution | Check audit log, retry |

---

## HTTP Error Reference

| Code | Meaning | Action |
|------|---------|--------|
| 400 | Bad request | Check request parameters |
| 401 | Unauthorized | Check API key / credentials |
| 403 | Forbidden | Check permissions and mode |
| 404 | Not found | Check resource ID or path |
| 429 | Rate limit | Wait and retry |
| 500 | Server error | Retry later |
| 502/503 | Service unavailable | Check API status |
| 504 | Gateway timeout | External API slow, retry |

---

## Debugging Checklist

### 1. Check Audit Log

1. Go to **MCP Gateway** → **Audit Log**
2. Find the failed call by timestamp
3. Review request parameters and response details
4. Check the error message and HTTP status code

### 2. Verify System Credentials

1. Go to **Systems** → select system → **Configure**
2. Click **Test Connection**
3. If failed, update credentials and retry

### 3. Check API Key Configuration

1. Go to **MCP Gateway** → **API Keys**
2. Verify the key is active (not revoked)
3. Check mode (Safe/Power)
4. Check project binding and Agent Profile

### 4. Check Project Integrations

1. Go to **Projects** → select project
2. Verify the system is listed in Project Integrations
3. Check allowed categories

### 5. Gateway Logs (Standalone Gateway)

For Docker gateway deployments:
```bash
docker compose logs -f gateway
```

---

## Contact Support

If issue persists:

1. Gather information:
   - API key ID (not the key itself)
   - Audit log entry / request ID
   - Complete error message
   - What you tried to do
   - When issue started

2. Contact:
   - In-app support
   - Email: support@adapterly.ai



------------------------------------------------------------


# Getting Started with Adapterly

Welcome to Adapterly! This tutorial will help you understand what Adapterly is, how it works, and how to connect your first system.

---

## What is Adapterly?

**Adapterly** is an MCP (Model Context Protocol) gateway that connects AI agents to external business systems. It turns REST APIs, GraphQL endpoints, and web services into MCP tools that AI agents like Claude, ChatGPT, and Cursor can use directly.

### Key Benefits

| Benefit | Description |
|---------|-------------|
| **Adapter Generator** | Create adapters from OpenAPI specs, HAR files, or manually |
| **MCP native** | Standard protocol supported by Claude, ChatGPT, Cursor, and others |
| **Project scoping** | Isolate integrations and control access per project |
| **Audit logging** | Every tool call is logged with full request/response details |
| **Secure** | Credentials stored encrypted, category-based access control |

### Common Use Cases

- **Cross-system queries** — Ask AI to combine data from multiple systems
- **Data entry automation** — Let AI create records in connected systems
- **Project management** — Query project data through natural language
- **Logistics tracking** — Check shipments and orders via AI

---

## How Adapterly Works

Adapterly follows a simple architecture:

```
System (e.g., My API)
  └── Interface (e.g., REST API)
        └── Resource (e.g., "projects")
              └── Action (e.g., "list", "get", "create")
                    └── MCP Tool (e.g., "my_api_projects_list")
```

Each system's resources and actions are automatically converted into MCP tools that AI agents can discover and call.

### Tool Naming

Tools follow the pattern: `{system_prefix}_{resource_alias}_{action_alias}`

Examples:
- `my_system_projects_list` — List all projects
- `my_system_items_get` — Get a specific item
- `my_system_orders_create` — Create an order

---

## Quick Start Guide

### Step 1: Create Adapters

Systems are created and managed through the web UI:

1. Go to **Systems** → **Create New System**
2. Use the **Adapter Generator** to import from:
   - **OpenAPI/Swagger spec** — Auto-discover all endpoints
   - **HAR file** — Record browser API calls, upload to generate adapter
   - **Manual** — Define endpoints one by one
3. Review and enable the endpoints you need

### Step 2: Configure Credentials

1. Go to **Systems** → select your system → **Configure**
2. Enter credentials based on the system's auth type:
   - **OAuth 2.0** — Client ID, secret, token URL
   - **API Key** — Key value and header name
   - **Bearer Token** — Pre-generated access token
   - **DRF Token** — Username and password (token auto-generated)
3. Click **Test Connection** to verify

### Step 3: Create a Project

1. Go to **Projects** → **Create New**
2. Give the project a name
3. Add **Project Integrations** — select which systems this project can access
4. Optionally restrict by tool categories

### Step 4: Generate an API Key

1. Go to **MCP Gateway** → **API Keys**
2. Click **Create API Key**
3. Choose mode:
   - **Safe** (default) — Read-only access
   - **Power** — Full read/write access
4. Optionally bind to a specific project
5. Copy the key (`ak_live_xxx`) — it won't be shown again

### Step 5: Connect Your AI Agent

Configure your MCP client with the Streamable HTTP endpoint:

```json
{
  "mcpServers": {
    "adapterly": {
      "url": "https://adapterly.ai/mcp/v1/",
      "headers": {
        "Authorization": "Bearer ak_live_xxx"
      }
    }
  }
}
```

Ask your AI agent: *"What Adapterly tools do you have access to?"*

---

## Example: Using System Tools

Here's what a typical interaction looks like:

```
User: "Show me all my projects"

AI calls: my_system_projects_list()

AI: "Here are your 5 projects:
    1. Project Alpha (active)
    2. Project Beta (active)
    3. Project Gamma (archived)
    ..."
```

```
User: "Get the details for Project Alpha"

AI calls: my_system_projects_get(id="abc-123")

AI: "Project Alpha:
    - Status: Active
    - Created: 2026-01-15
    - Members: 8
    ..."
```

---

## Security

- **API keys** control access — each key can be scoped to a project and mode
- **Agent Profiles** define reusable permission sets (allowed categories, included/excluded tools)
- **Audit logging** records every MCP tool call with timestamps, parameters, and results
- **Category-based access control** — tools are grouped into categories, policies restrict access at agent, project, and user levels

---

## Best Practices

1. **Start with Safe mode** — Use read-only access until you're confident in the setup
2. **Scope projects tightly** — Only include the systems each project actually needs
3. **Use Agent Profiles** — Create reusable profiles instead of configuring each key individually
4. **Monitor audit logs** — Review tool calls regularly for unexpected activity
5. **Rotate keys** — Regenerate API keys periodically

---

## Next Steps

1. **[Core Concepts](/help/en/concepts/)** — Understand projects, permissions, and gateway architecture
2. **[Guides](/help/en/guides/)** — Step-by-step instructions for specific tasks
3. **[Recipes](/help/en/recipes/)** — MCP usage examples and conversation patterns
4. **[MCP & Agents](/help/en/mcp/)** — Protocol details and connection setup



------------------------------------------------------------