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¶

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¶

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.