# MCP

Source: https://gokarla.io/docs/platform/ai/mcp

# Model Context Protocol (MCP)

<DocHero
  icon="Bot"
  eyebrow="Read-only · OAuth · Shop-scoped"
  title="Bring your Karla data into any AI assistant"
>
  The Karla MCP server lets AI assistants like Claude and ChatGPT query your
  delivery, order, claim, and campaign data in natural language — securely
  scoped to the shops you're allowed to see, and read-only by design.
</DocHero>

The [Model Context Protocol](https://modelcontextprotocol.io) is an open
standard for connecting AI assistants to external tools and data. Karla hosts a
remote MCP server, so you can connect a supported assistant once and start
asking questions about your business — no code, no data export.

## Connect your assistant

<FeatureGrid>
  <FeatureCard icon="Sparkles" title="Claude">
    Add Karla as a custom connector in Claude (desktop, web, or mobile) and sign
    in once. [Connect with Claude →](/docs/platform/ai/mcp-claude)
  </FeatureCard>
  <FeatureCard icon="MessageSquare" title="ChatGPT">
    Add Karla as an app in ChatGPT developer mode and authorize it. [Connect
    with ChatGPT →](/docs/platform/ai/mcp-chatgpt)
  </FeatureCard>
</FeatureGrid>

Any MCP-capable client works the same way — point it at the Karla server URL
below and complete the Karla sign-in when prompted.

## The server

Karla hosts a remote MCP server at:

```
https://mcp.gokarla.io/mcp
```

Add this URL as a **custom connector** (Claude) or **app / MCP server**
(ChatGPT and other clients). Your assistant walks you through sign-in
automatically — there is nothing to copy or paste.

## Authentication & access

Karla MCP uses **OAuth 2.0** — you sign in with your Karla account, the same way
you sign in to the portal. There are **no API keys or passwords to paste** into
your assistant.

- When you add the connector, your assistant opens the Karla sign-in page. Sign
  in with Google or Microsoft, then approve the connection on the consent
  screen.
- Access is tied to your Karla user and your shop permissions. The assistant
  receives a scoped token — never your password.
- You need a Karla account that has been **invited to at least one shop**. If you
  don't have access yet, ask a colleague who is an admin on your shop to invite
  you from the portal.

You can revoke access at any time from your assistant's connection settings, or
by removing the connector.

## Security & privacy

- **Shop-scoped.** Every tool only returns data for the shops your account is
  authorized for.
- **Read-only.** Every Karla tool only reads data. Nothing the assistant can do
  through MCP creates, edits, or deletes anything in your account.
- **Customer privacy by design.** Personal customer details are minimized before
  they ever reach the assistant: email addresses are masked, and no customer
  name, street address, or phone number is shared — only coarse location such as
  the postal code.
- **Encrypted in transit.** All traffic uses HTTPS.

## Available tools

All tools are read-only.

| Tool                    | What it does                                                     |
| ----------------------- | ---------------------------------------------------------------- |
| `list_accessible_shops` | Discover which shops you can query, and your role on each        |
| `get_shop`              | Shop identity, status, and contact details                       |
| `find_orders`           | Search and retrieve order records                                |
| `find_shipments`        | Search and retrieve shipment records (tracking, carrier, status) |
| `get_shipment_events`   | Full delivery event timeline for one tracking number             |
| `find_campaigns`        | Search campaigns and their live lifecycle status                 |
| `find_discounts`        | Search discount codes and their configuration                    |
| `list_products`         | Browse the shop's product catalog                                |
| `find_claims`           | Search claim records (lost, damaged, carrier disputes)           |
| `get_claim`             | Retrieve a single claim by its ID                                |

### Shop scoping

You normally **don't** pass a shop — tools default to all shops your account can
access. If you have more than one shop, narrow a query by naming it:

> "Show me orders for my-shop-a only."

### Example prompts

Once connected, start by discovering your access, then ask away:

> "What shops can I access?"
>
> "Show me orders from the last 7 days."
>
> "Look up the delivery events for tracking number TRACK123."
>
> "Which shipments are still in transit?"
>
> "List my currently active campaigns."
>
> "Show me open claims from this month."
>
> "What discount codes do I have, and which are percentage-based?"

### Dates and pagination

- **Dates** use ISO format: `YYYY-MM-DD` (for example, `2024-01-15`).
- **Pagination** uses `limit` (up to 100 records per shop) and `offset`. Ask for
  "the next 50 orders" and the assistant will page for you.

### Rate limit

Each user can make up to **120 tool calls per minute**. If you hit the limit,
wait a moment and continue.

## Data freshness

Results are live — they reflect the same data you see in the Karla portal,
updated in real time.

## Troubleshooting

### The assistant says it isn't connected, or sign-in fails

Re-add the connector and complete the Karla sign-in in the window that opens.
Make sure you finish on the consent screen and that pop-ups aren't blocked.

### "No shops are pre-associated with your account"

Your Karla user hasn't been invited to a shop yet. Ask an admin on your shop to
invite you, then reconnect.

### "Access denied to shops…"

You asked for a shop your account can't access. Run `list_accessible_shops` (or
ask "what shops can I access?") to see your options.

### Empty results

- Check date filters — dates must be `YYYY-MM-DD`.
- Broaden the query (remove a date range or narrow filter).
- Confirm the shop has data for that period.

### "Rate limit exceeded"

You've made more than 120 tool calls in a minute. Pause briefly and continue.