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

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:

// 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):

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

Claude Code (.claude/settings.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:

{
  "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¶

{
  "page": 1,
  "pageSize": 100,
  "fetch_all_pages": true
}

Get Actions¶

{
  "id": "project-uuid-here"
}

Create Actions¶

{
  "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:

{
  "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.