> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect AI agents and assistants to the Sendcloud Public API v3 through the Model Context Protocol.

The Sendcloud **MCP server** exposes the [Public API v3](/api/v3) to AI assistants and agents through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Every API operation (for example creating shipments, listing orders, tracking parcels, and more) is available as a **tool** your MCP client can call, so an agent can act on your Sendcloud account in natural language without you writing any HTTP code.

It is an *aggregated* server: a single endpoint that bundles every Public API v3 domain as a separate **toolset**. You connect once and get access to all of them, or narrow the connection to just the toolsets you need.

<Info>
  This page describes how to **use** the MCP server as an agent or MCP client. For the underlying endpoints and schemas,
  see the [API v3 reference](/api/v3).
</Info>

## Endpoint

| | |
| - | - |
| **MCP URL** | `https://mcp.sendcloud.com/mcp` |
| **Transport** | Streamable HTTP |
| **Authentication** | OAuth 2.0 (bearer token) |

The server speaks the standard MCP protocol over HTTP, so most MCP clients can connect to it, including Claude, Claude Code, ChatGPT, VS Code, and agents built on an MCP SDK.

<Note>
  Your MCP client must support [OAuth Client ID Metadata Documents
  (CIMD)](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#client-id-metadata-documents) to
  sign in. Some clients don't support CIMD yet and can't connect to the Sendcloud MCP server, for example
  [**Cursor**](https://forum.cursor.com/t/mcp-oauth-cimd-support-plans-and-timelines/148096).
</Note>

<Warning>
  **Before you connect – please read.**

  **Results are reference information only.** This connector lets your AI assistant read data already available to you via the Sendcloud API (e.g. shipment status, tracking, rates, order details). That data reflects a snapshot at the time your AI assistant made the request and can change afterwards – for example, carrier surcharges, tracking status, and delivery estimates update over time. Do not treat a response from your AI assistant as a confirmed or binding figure; for anything time-sensitive or in dispute (e.g. a surcharge query), check your Sendcloud account directly or contact Sendcloud support.

  **Sendcloud does not control your AI assistant's output.** We cannot control, and are not responsible for, how your chosen AI assistant interprets, summarises, or responds to this data, including any follow-up questions or attempts to get it to “confirm” a figure.

  **You choose the AI tool.** You are solely responsible for selecting the AI assistant you connect to this feature. Sendcloud does not select, endorse, or control that AI provider, and has no visibility into or control over how it subsequently stores, uses, or discloses the data it receives – that is governed by your own agreement with that provider, not by Sendcloud.

  By connecting, you confirm you have read and accept the above.
</Warning>

## Connecting

<Steps>
  <Step title="Add the server to your MCP client">
    Point your client at the MCP URL. For example, with the Claude Code CLI:

    ```bash theme={null}
    claude mcp add --transport http sendcloud https://mcp.sendcloud.com/mcp
    ```

    Other clients (Claude Desktop, custom agents) accept the same URL in their MCP server configuration. A typical JSON config looks like:

    ```json theme={null}
    {
      "mcpServers": {
        "sendcloud": {
          "type": "http",
          "url": "https://mcp.sendcloud.com/mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Authorize with OAuth 2.0">
    The first time your client connects, it discovers the authorization server automatically (via [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata) and walks you through an OAuth 2.0 sign-in at `account.sendcloud.com`. The consent screen lets you pick which permission groups to grant (see [Choosing permissions](#choosing-permissions)). After you approve access, the client stores the resulting token and attaches it to every tool call.

    Your credentials live in the MCP client, never in the server. See [Authentication](/docs/getting-started/authentication) for how Sendcloud OAuth 2.0 works.
  </Step>

  <Step title="Discover and call tools">
    Once connected, the client lists the available tools. Ask the agent to perform a task (for example *"list my most recent orders"* or *"track parcel 123456789"*) and it selects and calls the matching tool, forwarding the request to the Public API v3 and returning the response.
  </Step>
</Steps>

## Selecting toolsets

By default the server exposes **all** toolsets. To limit a connection to a subset (for example keeping the agent's tool list focused and relevant) add a `?toolsets=` query parameter with a comma-separated list of toolset names:

```bash theme={null}
# Only the orders and shipments tools
claude mcp add --transport http sendcloud "https://mcp.sendcloud.com/mcp?toolsets=orders,shipments"
```

The filter applies to both tool discovery and tool calls: a tool outside the selected toolsets is hidden from the list *and* rejected if called directly.

## Choosing permissions

When you authorize the connection, the consent screen lists permission groups such as **Orders**, **Shipping**, and **Returns**. Each group grants a set of OAuth 2.0 **scopes**, and the token your client receives can only do what those scopes allow.

Toolsets control which tools the agent sees. Scopes control what the agent is allowed to do with your account. For example, you can let an agent read your parcels without allowing it to create or announce shipments.

<Tip>
  Grant only the groups your agent needs. A tool that needs a scope you didn't grant fails with a permission error,
  which is the expected result.
</Tip>

To change your permissions, re-authenticate the connection in your MCP client and select a different set of groups. See [Scopes for OAuth apps](/api/v3/scopes) for the scopes in each group.

## Available toolsets

Each toolset maps to one Public API v3 domain. Its tools need the scopes for that domain, as listed in [Scopes for OAuth apps](/api/v3/scopes).

| Toolset | What it covers |
| - | - |
| `analytics` | Carrier and shipping-option transit times |
| `brands` | Brands configured on your account |
| `carriers-dp` | Carrier delivery-point order finalization |
| `compat` | Compatibility shipping-options endpoint |
| `contracts` | Carrier contracts and their schemas |
| `duties-and-taxes` | Duties and taxes calculations |
| `dynamic-checkout` | Checkout delivery options |
| `event-subscriptions` | Webhook subscriptions and connections |
| `integrations` | Integrations, logs, and order-status mappings |
| `orders` | Create, list, retrieve, update, and delete orders |
| `organization` | Organization metadata |
| `parcel-documents` | Retrieve parcel documents |
| `parcel-statuses` | Parcel status definitions |
| `parcel-tracking` | Register and retrieve tracking |
| `pickups` | Schedule and retrieve pickups |
| `reporting` | Parcel reports |
| `returns` | Create, validate, and manage returns |
| `sender-addresses` | Sender addresses |
| `service-points` | Service-point lookup and availability |
| `ship-an-order` | Create labels for orders (sync and async) |
| `shipments` | Create, announce, cancel, and retrieve shipments; validate addresses |
| `shipping-options` | Fetch shipping options and quotes |
| `support` | Support tickets, carrier contacts, and documents |
| `user` | User authentication metadata |

## How tools map to the API

<AccordionGroup>
  <Accordion title="Tool naming and namespacing">
    Each tool corresponds to one HTTP operation. The tool name is derived from the operation's `operationId`, and is **namespaced by toolset** to avoid collisions — for example `orders_sc_public_v3_orders_get_list_orders` (list orders) or `shipments_sc_public_v3_scp_get_shipment_by_id` (retrieve a shipment).

    The operation's path, query, and header parameters — plus the request-body fields — become the tool's arguments. Required API parameters stay required on the tool.
  </Accordion>

  <Accordion title="Safety annotations">
    Tools are annotated with hints about their effect, derived from the HTTP method: read-only (`GET`), idempotent, or destructive (`DELETE`, `POST`). MCP clients use these to auto-confirm safe lookups while prompting you before a tool that creates, cancels, or deletes data.

    <Warning>
      Tools that create or cancel shipments act on your live account. As with the API directly, you may be invoiced for shipments you create if they aren't cancelled within the cancellation deadline.
    </Warning>
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/getting-started/authentication" horizontal>
    How Sendcloud OAuth 2.0 works
  </Card>

  <Card title="Scopes" icon="lock" href="/api/v3/scopes" horizontal>
    The permissions each consent group grants
  </Card>

  <Card title="API v3 reference" icon="cog" href="/api/v3" horizontal>
    The endpoints behind every MCP tool
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.