MCP: connect an AI assistant

MCP (Model Context Protocol) is the standard that lets an AI assistant connect to an external service and actually use it, not just talk about it. Once Yellohu is connected to your assistant, you can ask for a quote, create a shipment, check a tracking, or book a pickup just by writing in natural language: the assistant calls the API for you.

You need a dedicated key (different from your direct API integration key, if you already have one) and an MCP-compatible client: instructions for the main ones are below.

Go to the dashboard, Integrations section, "MCP" card. Generate a Sandbox key to try it risk-free (it never touches real couriers or payments), or a Live key for real actions. Either way, every action that creates or cancels something still requires your explicit confirmation before it actually runs.

Right after creating it you'll also see a ready-to-copy configuration snippet: the instructions below tell you where to paste it for each client.

1. 1

   Don't use Settings → Connectors

   That screen in Claude Desktop only supports OAuth authentication, not an API key like ours. The right path is editing the configuration file directly.

2. 2

   Open the configuration file

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Windows: %APPDATA%\Claude\claude_desktop_config.json. Create it if it doesn't exist yet.

3. 3

   Add the configuration

   Claude Desktop rejects a remote server configured with just "url" and "headers" (it flags it as an invalid entry and ignores it): you need a local bridge via npx, the mcp-remote package, which forwards requests to the real server while adding the authentication header. Paste (or merge, if the file already has other servers) the block below, replacing yh_mcp_live_xxx with your key.

4. 4

   Restart Claude Desktop

   Quit and reopen the app so the new configuration is picked up.

Claude Desktop doesn't support a remote MCP server configured directly with "url"/"headers": it requires the local mcp-remote bridge (via npx, needs Node.js installed).

{
  "mcpServers": {
    "yellohu": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://yellohu.com/api/mcp",
        "--header",
        "X-Api-Key:${YELLOHU_MCP_KEY}"
      ],
      "env": {
        "YELLOHU_MCP_KEY": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Run the command

   A single terminal command, no file editing needed.

claude mcp add --transport http yellohu https://yellohu.com/api/mcp --header "X-Api-Key: yh_mcp_live_xxx"

1. 1

   Open (or create) the configuration file

   .cursor/mcp.json in your project folder, or the global configuration from Cursor's MCP settings.

2. 2

   Add the configuration

   Paste (or merge) the block below with your key.

{
  "mcpServers": {
    "yellohu": {
      "url": "https://yellohu.com/api/mcp",
      "headers": {
        "X-Api-Key": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Open the .vscode/mcp.json file

   It must be specifically this file (workspace, .vscode folder), not a generic .mcp.json at the project root: a known VS Code bug silently drops the auth header in that second case.

2. 2

   Add the configuration

   Two differences from the other clients: the root key is "servers", not "mcpServers", and an explicit "type": "http" field is required.

VS Code uses a slightly different format from the other clients: "servers" key (not "mcpServers"), and a required "type" field.

{
  "servers": {
    "yellohu": {
      "type": "http",
      "url": "https://yellohu.com/api/mcp",
      "headers": {
        "X-Api-Key": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Open the configuration file

   ~/.codeium/windsurf/mcp_config.json.

2. 2

   Add the configuration

   Note: Windsurf calls the URL field "serverUrl", not "url" like other clients. Copying a config from another client without renaming this field is the most common mistake.

Windsurf uses "serverUrl", not "url", for the server address.

{
  "mcpServers": {
    "yellohu": {
      "serverUrl": "https://yellohu.com/api/mcp",
      "headers": {
        "X-Api-Key": "yh_mcp_live_xxx"
      }
    }
  }
}

1. 1

   Enable developer mode

   Settings → Connectors → Advanced settings → turn on "Developer mode" (requires a Plus, Pro, Team, Enterprise, or Edu plan).

2. 2

   Add a new connector

   Enter the server URL (https://yellohu.com/api/mcp) and choose "API key" authentication (not OAuth).

3. 3

   Verify it actually works

   ChatGPT's UI for this is the newest of the seven and may change: if the auth field doesn't let you pick the header name, try entering the key anyway and immediately ask for a quote to confirm the connection actually responds before relying on it.

The newest and most in-flux of the seven integrations: always verify with a real request that the connection works.

URL: https://yellohu.com/api/mcp
Auth: API key
Header: X-Api-Key

1. 1

   Open (or create) ~/.codex/config.toml

   You can also use .codex/config.toml inside your project folder instead of your home directory. The "codex mcp add" command only works for local (stdio) servers, not remote ones like this: it has to be configured by hand in the file.

2. 2

   Add the configuration

   Paste the block below with your key. Note: Codex uses TOML format, not JSON like the other clients.

Codex uses TOML instead of JSON and has no terminal command for remote servers: it always has to be configured by editing the file.

[mcp_servers.yellohu]
url = "https://yellohu.com/api/mcp"
http_headers = { "X-Api-Key" = "yh_mcp_live_xxx" }

Any MCP client that supports a remote server over Streamable HTTP works the same way: same two values, only the field names may differ per client. Check your client's docs to see what it calls the URL and header fields.

URL: https://yellohu.com/api/mcp
Header: X-Api-Key: yh_mcp_live_xxx

Actions that really create or cancel something (creating a shipment, cancelling it, booking a pickup) never happen on the first try. The assistant always shows you a summary (courier, price, addresses) and waits for you to explicitly say to proceed, before actually running the action. You never need to type a technical command to confirm: just reply normally, like you would to a person.

You can customize this behavior per action (creating a shipment, cancelling one, booking a pickup) from the dashboard, Integrations section, MCP, "Tool authorizations" card: you can choose to run it immediately without asking for confirmation, to always require it (the behavior just described, the default), or to disable it entirely for the AI assistant.