MCP Server

The PostCo MCP server is how AI clients connect to PostCo. Claude Code, Claude Desktop, ChatGPT, and any other client that speaks the Model Context Protocol can work with your PostCo data directly.

What you can ask

Once connected, your AI client answers questions like these by calling the server's tools on your behalf:

"How many returns did we get last month compared to the month before?"
"What are the top five return reasons for our footwear SKUs this quarter?"
"Break refund amount down by country over the last 90 days."
"Find return order #1042 and tell me what's on it."
"Which returns from last week are still waiting to be reviewed?"

The client decides which tools to call. The MCP Tools reference lists everything it can call and what each tool returns.

Adding the server in Claude

You can add the MCP server as a custom connector in Claude. Open Customize, then Connectors, and click Add.

Claude's Connectors settings, with the Add custom connector button at the top of the list — Step 1. Settings, Connectors, Add custom connector.

Choose the server name, any valid name is fine, and paste https://mcp.postco.co/mcp as the URL.

The custom connector dialog, with a name filled in and the PostCo MCP endpoint in the URL field — Step 2. Any name, and the endpoint as the URL.

Leave the advanced settings alone. Scroll to the bottom and click Add.

The bottom of the custom connector dialog, with the advanced settings untouched and the Add button below them — Step 3. Advanced settings stay as they are.

Claude opens a browser to sign you in. Signing in covers the two ways to do that, and Approving the connection covers the consent screen. Once approved, the server appears in your connector list.

The Connectors list with PostCo present as a connected custom connector — Step 4. PostCo, connected.

Adding the server in ChatGPT app

A custom MCP server can only be added in the desktop app. Please note that ChatGPT on the web and ChatGPT Classic client only support adding MCP servers in developer mode.

Go to Plugins, click on the ⚙️ button.

The desktop app's Plugins view, with Plugins selected in the sidebar and the Add button above the list — Step 1. Plugins, in the sidebar, then ⚙️.

Open the Add menu and choose Add MCP server.

The Add menu open on the Plugins settings page, with Add MCP server highlighted below Create plugin and Add a marketplace — Step 2. Add, then Add MCP server.

Name it anything you like, and set Type to Streamable HTTP. Paste https://mcp.postco.co/mcp as the URL, and leave Bearer token env var and both header fields empty, then Save.

The Connect to a custom MCP form, with a name filled in, Streamable HTTP selected as the type, the PostCo MCP endpoint as the URL, and the bearer token and header fields left empty — Step 3. Streamable HTTP, the endpoint, nothing else.

The server now appears under MCPs, switched on but not yet connected. Click Authenticate on its row.

The MCPs tab listing postco-mcp among the servers, with an Authenticate button on its row — Step 4. Authenticate, on the server's row.

That opens a browser. Signing in covers the two ways to do it, and Approving the connection covers the consent screen.

Connecting a client

Connections are authorized with OAuth 2.1. The Bearer token API keys used by the REST API do not work here, and MCP tokens do not work against the REST API.

The server works with any client that connects over the web and can sign you in through a browser. Clients that only run a local command cannot connect.

Add the server: register https://mcp.postco.co/mcp with your client, as shown below.
Sign in: your client opens a browser.
Approve: read the consent screen, then approve the connection.

Clients configured by file or command

Claude Code

claude mcp add --transport http postco https://mcp.postco.co/mcp

Cursor — .cursor/mcp.json for one project, ~/.cursor/mcp.json for all

{
  "mcpServers": {
    "postco": {
      "url": "https://mcp.postco.co/mcp"
    }
  }
}

VS Code — .vscode/mcp.json, where the key is "servers"

{
  "servers": {
    "postco": {
      "type": "http",
      "url": "https://mcp.postco.co/mcp"
    }
  }
}

Other clients

{
  "mcpServers": {
    "postco": {
      "type": "http",
      "url": "https://mcp.postco.co/mcp"
    }
  }
}

Signing in

You can sign in two ways, and the choice determines how the connection is recorded.

Name
Continue with Shopify
Description
Enter your store domain and authorize through Shopify. This proves you control the shop but does not identify you individually, so the connection is recorded and revoked at shop level.
Name
Sign in with email and password
Description
Enter your store domain, email, and password. This identifies you individually, so the connection can be audited and revoked per person.

Staff accounts with the manage return access only role cannot authorize a connection.

The consent screen names the client requesting access, the shop the connection will be scoped to, and the permissions being granted. Each permission is listed with what it covers, and they are separate: figures, individual records over a date range, and single return orders looked up by id or order name. Read the screen in full before approving, particularly the client identity, which is the only part a lookalike client cannot fake. Data handling covers what data those permissions allow to leave PostCo.

A connection is scoped to the one shop you signed in to. The client cannot ask for another shop's data, and a call that tries is refused.

If your client is being redirected to localhost or another loopback address, the consent screen says so. Any local process can claim a loopback port, so approve only if you started that client yourself.

Data handling

Connecting an AI client means data about your shop leaves PostCo and enters that client, and for a hosted client, its model provider.

Name
What the tools can return
Description
Aggregate figures for any metric the connection was approved for, and individual records through list_records, list_return_orders, and get_return_order. Some metrics are themselves keyed by customer, so an aggregate is not always impersonal: the catalog marks each metric aggregate or identifying, and Metrics lists which is which.
Name
What the tools cannot do
Description
Change anything. Every tool reads; none writes, and nothing the server exposes can create, edit, or delete data in your PostCo account.
Name
What is never returned
Description
Narrative the customer wrote — return item notes and free-text question answers — which is withheld to avoid prompt injection. Addresses and contact details are not narrative and are returned where a tool's permission allows. Every withheld field is named in meta.excluded_fields, so a redaction is visible rather than silent.
Name
Who receives it
Description
Your AI client, and the provider running the model behind it. Once a response leaves PostCo it is handled under that provider's terms, not ours. Treat a connection the way you would treat exporting the same report.
Name
What PostCo records
Description
Consent and revocation are recorded against your shop, and every tool call is recorded with what was asked. The values returned are not recorded.
Name
What PostCo never receives
Description
Your conversation. Prompts, replies, and chat history stay in your AI client. PostCo sees only the tool arguments it decided to send.
Name
What you control
Description
Whether to connect at all, which account you connect with, and which questions you ask. Row-level records and the identifying metrics are the ones that reach named customers. A connection can be ended at any time; see Disconnecting.

PostCo's handling of the underlying data is governed by our Privacy Policy and Terms of Service. For questions about what a specific dataset contains before you connect, contact support@postco.co.

Disconnecting

Remove the server from your client to end the connection locally. In Claude, ChatGPT, and other clients configured through their settings, disconnect or delete the connector there. In Claude Code:

Remove the server

claude mcp remove postco

To revoke access centrally, if a machine is lost or someone leaves, contact support@postco.co. A revoked connection stops working immediately and reaches no data, and it cannot be restored by reconnecting; see Errors.

What's next?

Read the MCP Tools reference for every tool, its arguments, and what it returns
Browse the REST API for programmatic access to return orders from your own code
Read about authentication for API keys, which are separate from MCP connections