Model Context Protocol (MCP)

The Karla MCP server lets AI agents query your delivery, order, and campaign data through natural language. Connect it to tools like Claude Desktop, Cursor, Windsurf, or workflow platforms like N8N — and start asking questions about your business.

What you can do

• Find orders — search by date, email, country, amount, financial status, or order number
• Track shipments — look up by tracking number, carrier, phase, direction, or delivery status
• Track delivery events — get the full event timeline for a specific shipment
• Browse campaigns — filter by type, date range, or active status
• Browse discounts — search discount codes by code, type, or value
• Analyze orders — count orders, calculate revenue, or compute average order value grouped by day/week/month/country
• Analyze shipments — get delivery rates, find delayed shipments, compare carrier performance
• Analyze campaigns — measure CTR, conversions, revenue, and compare campaign performance

All data is automatically scoped to your shop — you can only access data that belongs to shops assigned to your API key.

Remote server

Karla hosts a Streamable HTTP MCP server at:

https://mcp.gokarla.io/mcp

Authentication uses HTTP Basic Auth (same credentials as the Karla REST API).

Getting started

1. Get your API credentials

You need a username (your merchant slug) and an API key. Contact your Karla account manager or create one in the Karla dashboard under Settings > API Keys.

2. Connect your MCP client

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "karla": {
      "type": "streamable-http",
      "url": "https://mcp.gokarla.io/mcp",
      "headers": {
        "Authorization": "Basic <base64(username:api_key)>"
      }
    }
  }
}

Replace <base64(username:api_key)> with your Base64-encoded credentials. For example, if your username is my-shop and API key is sk-abc123, encode my-shop:sk-abc123.

Cursor / Windsurf

Add to your MCP settings (.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "karla": {
      "type": "streamable-http",
      "url": "https://mcp.gokarla.io/mcp",
      "headers": {
        "Authorization": "Basic <base64(username:api_key)>"
      }
    }
  }
}

3. Start querying

Once connected, your AI agent can call Karla tools directly. Start by discovering your shops:

"What shops do I have access to?"

Then ask questions like:

"Show me orders from the last 7 days"

"What's my delivery rate this month?"

"Find delayed shipments with DHL"

"Compare my top 5 campaigns by revenue"

"Show me the tracking events for shipment TRACK123"

"List all active discount codes"

"What's the average order value by country this quarter?"

Available tools

Tool	Description
list_accessible_shops	Discover which shops your API key can access
find_orders	Search and retrieve order records
find_shipments	Search and retrieve shipment records
get_shipment_events	Get delivery tracking events for a specific shipment
find_campaigns	Search and retrieve campaign records
find_discounts	Search and retrieve discount codes and configurations
analyze_orders	Order analytics (count, revenue, AOV) with grouping
analyze_shipments	Shipment performance, delays, carrier and phase breakdowns
analyze_campaigns	Campaign CTR, conversions, revenue, and comparison

Shop scoping

All tools automatically scope data to your authorized shops. You do not need to pass a shop_slugs parameter — it defaults to all shops on your API key.

If your API key has access to multiple shops, you can narrow your query to a specific one:

"Show me orders from my-shop-a only"

important

You can only access data from shops assigned to your API key. Attempting to query other shops will return an access denied error.

Date format

All date filters use ISO format: YYYY-MM-DD (e.g., 2024-01-15).

Pagination

Data retrieval tools (find_orders, find_shipments, find_campaigns, find_discounts) support pagination with limit and offset parameters. Use these to page through large result sets:

"Show me the next 50 orders starting from offset 100"

Rate limit

Each API key is limited to 60 requests per minute. If you exceed this, wait a moment and try again.

Data freshness

The MCP server optimizes data for analytics and large-scale lookups. As such, recent orders or shipments may take a few hours to appear in results. If you need to check live or just-created records, use the REST API instead.

Security

All data is strictly isolated to your shop. Your API key determines which shops you can access, and every query is scoped accordingly — there is no way to access another merchant's data. All connections use HTTPS.

Troubleshooting

"Authentication required" error

Your credentials are missing or invalid. Verify:

• The Authorization header uses Basic scheme (not Bearer)
• Credentials are correctly Base64-encoded as username:api_key
• Your API key has not expired

"Access denied to shops" error

You requested a shop slug that is not assigned to your API key. Use list_accessible_shops to see which shops you can access.

Empty results

• Check your date filters — dates use YYYY-MM-DD format
• Verify the shop has data for the requested time period
• Try broadening your filters (remove date range or country filter)

"Rate limit exceeded" error

You've exceeded 60 requests per minute. Wait a moment and try again, or reduce the frequency of your queries.