> ## 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.

<Warning>The MCP server is currently in closed beta. We plan to make it more widely available soon.</Warning>

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 any MCP-compatible client (for example Claude, Claude Code, Cursor, or your own agent built on an MCP SDK) can connect to it.

## 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 (Cursor, 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`. 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.

    <Note>
      OAuth 2.0 is currently available as a beta feature for a limited number of clients. Reach out to Sendcloud if your account is not yet enabled.
    </Note>
  </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.

## Available toolsets

Each toolset maps to one Public API v3 domain.

| 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                                    |
| `store-locations`     | Store-location management                                            |
| `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="Intent capture">
    Every tool call includes an `intent_summary` argument: a short, natural-language statement of *why* the agent is
    calling the tool. It is used for product analytics and is stripped before the request reaches the Public API — it
    never changes the API call itself.
  </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="API v3 reference" icon="cog" href="/api/v3" horizontal>
    The endpoints behind every MCP tool
  </Card>
</CardGroup>