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.

Official listings

Claude

Listed in Claude's connector directory.

Connect to Claude Setup guide

ChatGPT

Listed in ChatGPT's plugin directory.

Install plugin Setup guide

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.

PostCo is listed in Claude's connector directory. Open the link, then Connect to Claude. 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.

Adding as a custom connector

PostCo MCP can also be added as a custom connector. 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, the same as it does for the listed connector. 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

PostCo is listed in ChatGPT's plugin directory. Open the link, then Install plugin. ChatGPT opens a browser to sign you in; Signing in covers the two ways to do that, and Approving the connection covers the consent screen.

Adding as a custom MCP server in the desktop app

This adds the server to the desktop app's Codex sessions, which share the same configuration as the Codex CLI and IDE extension. Ordinary ChatGPT conversations do not use it: ChatGPT on the web reads none of this, and can add a custom MCP server only in developer mode.

In the desktop app, 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.

Two things to know about asking in the desktop app. The server is reachable in Work mode, not in Chat mode, so switch modes if a question comes back with nothing from PostCo. And name PostCo in the question itself – "can you check how many returns we had last month using the PostCo MCP", for example – because the app does not reliably reach a connected server on its own.

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.

Continue with Shopify. 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 ended at shop level.

Sign in with email and password. Enter your store domain, email, and password. This identifies you individually, so the connection can be audited and ended per person.

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

Approving the 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: return figures, individual records over a date range, single return orders looked up by id or order name, and how many orders the store took over a date range. 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.

What the tools can return. 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. Where the connection was approved for it, how many orders your store took over a date range, as a count only: no order contents, customers or revenue.

What the tools cannot do. Change anything. Every tool reads; none writes, and nothing the server exposes can create, edit, or delete data in your PostCo account.

What is never returned. 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.

Who receives it. 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.

What PostCo records. When a connection is approved and when it ends are recorded against your shop, and every tool call is recorded with what was asked. The values returned are not recorded.

What PostCo never receives. Your conversation. Prompts, replies, and chat history stay in your AI client. PostCo sees only the tool arguments it decided to send.

What you control. 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 Removing the server.

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/Removing the server

In Claude

Open Customize, then the Connectors tab, then Yours, and click PostCo in the list.

Claude's Customize page with the Connectors tab open, Yours selected, and PostCo in the connector list — Step 1. Customize, Connectors, Yours, then PostCo.

Click Disconnect at the top of the connector's page. This is the step that cuts off access, so connecting again later asks for your approval afresh.

The PostCo connector page with the Disconnect button at the top right — Step 2. Disconnect, at the top of the page.

Disconnecting leaves the connector on the list with no tools available. To take it off the list entirely, open the ⋮ menu beside Disconnect and click Remove. Disconnect first if you want access ended as well.

The PostCo connector page with the three-dot menu open and Remove highlighted below View details and Refresh tools list — Step 3. The ⋮ menu, then Remove.

In Claude Code

Remove the server

claude mcp remove postco

In the ChatGPT desktop app

Open Settings, then Plugins, then the MCPs tab. The server is listed under Servers, with a toggle and a ⚙️ button on its row.

The Plugins settings page with Plugins selected in the sidebar and the MCPs tab open, numbered one and two — Step 1. Plugins, in the sidebar, then the MCPs tab.

Switching the toggle off disables the server and keeps its configuration, so you can switch it back on later without setting it up again.

The MCPs tab with the toggle on the postco-mcp row highlighted — Step 2. The toggle disables the server without removing it.

The app has no separate disconnect, so ask us to end the connection if you need access itself gone rather than only stopped here. To remove the server outright, click the ⚙️ button on its row.

The MCPs tab with the gear button on the postco-mcp row highlighted — Step 3. The gear opens the server's settings.

On the settings page that opens, click Uninstall.

The server's settings page, titled Update Postco-mcp MCP, with the Uninstall button at the top right — Step 4. Uninstall, at the top right of that page.

To end a connection from our side, if a laptop is lost or someone leaves, contact support@postco.co. It stops working immediately and reaches no data, and it cannot be brought back — connecting again starts over, with a new approval. See Errors for what a client sees once a connection has ended.

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