Skip to main content

Connect your AI assistant with Ordering MCP

Use the Ordering.co MCP server to let Claude Code or Codex discover and run supported operations with your project permissions. Start with a read-only key to check your identity and query orders without granting write access.

MCP exposes a selected catalog of API operations, not unrestricted access to the entire API. It uses Streamable HTTP and a personal MCP key, not an API key or a Dashboard session token.

Connect with one prompt​

Paste this into a terminal AI agent on the machine where your MCP client runs:

Connect me to Ordering.co: clone https://github.com/Ordering-co/ordering-dev-quickstart to ~/ordering-dev-quickstart (or pull it if I already have it), then read its SETUP.md and follow it step by step.
  1. The agent follows quickstart SETUP.md, starts login start --install and gives you a private link and verification code. The plain /connect/ URL needs that pairing; it is not a standalone installer.
  2. Open the link, sign in through Dashboard or Accounts (Billing), choose your project and enter the code from the agent. Use your own enabled administrator or business manager account; confirm the data notice and permissions.
  3. Keep MCP read unless you need supported changes. REST API is a separate option, checked by default, with broad permissions of your user and no expiration. Uncheck it if unnecessary: MCP read does not make REST read-only. An existing same-project REST credential is kept with a warning when no replacement is delivered; unchecking does not remove or revoke it.
  4. Wait for the terminal to finish login wait. Browser success means credentials were delivered, not that clients were installed. The terminal checks identity, the launcher and each detected client registration. If authentication succeeded but installation failed, retry ./ordering install, then ./ordering clients; do not repeat login only for that failure.
  5. Reload/restart your intended client, approve its normal MCP trust prompt and ask “Who am I in Ordering?”. Confirm an actual whoami tool call identifies the intended account/project. Then discover, describe and read the latest five orders, requesting only needed fields. An empty permitted result is valid.

Use only data you are authorized to share with the AI provider. There is no automatic sandbox; never publish credentials, pairing codes, raw identities or customer responses as setup evidence.

Requirements and compatibility​

Browser pairing uses Bash, curl and OpenSSL; global registration requires Node.js 22+ and npm. Use macOS/Linux, or clients running inside WSL. A remote/cloud session installs on its own execution machine, not the computer used for sign-in. WSL does not configure native Windows desktop apps. Keep the checkout in its installation location: moving it or Node requires install again.

ClientWhat the installer supportsWhat you still verify
Claude Code, CodexDetected native user configuration and stdio launcherReload/trust, runtime tools and a client-side authenticated call
Claude Desktop, Cursor, VS CodeDetected native global configurationApplication enablement/reload; VS Code needs MCP/Copilot Agent mode
OpenCodeNative version-aware config; version 2 runtime activationLocation-specific runtime and client-side identity/read
Other supported clientsOnly clients detected by the locked adapterNo guarantee that every application or LLM was tested
PiAdditional MCP adapter needed; skipped automaticallyInstall and configure its supported adapter separately
Hosted/cloud connectors, native Windows appsNot configured by the local/WSL installerUse a supported client-specific path; local configs do not connect cloud services

Configuration formats and protocol fixtures are tested separately from live clients. Record OS/client version → detection → config read-back → runtime → authenticated call → reload/trust pending. A registered config or launcher probe does not prove every GUI is connected. See the quickstart client reference for current coverage and release dependencies.

Server, quickstart and plugin​

  • MCP server: authorizes a selected operation catalog, subject to project, role, scope and allowed fields. It does not expose the entire API.
  • Quickstart: browser pairing, local credential lifecycle, launcher, detected client registration and optional REST/OpenAPI helper.
  • Plugin and skill: optional platform knowledge for Claude Code/Codex, installed separately. Follow its version-specific README to avoid duplicate legacy plugin/project servers. Installing quickstart does not automatically install the plugin.

If a repository or marketplace refuses access, use the manual alternative below or request repository access. An Ordering account does not itself grant GitHub access. Do not put a key into plugin command arguments or chat.

Renew, recover and disconnect​

cd ~/ordering-dev-quickstart
./ordering doctor
./ordering clients
./ordering login --install # renew through browser sign-in

Pairing defaults to 30 days; manual MCP creation defaults to 7, currently capped at 365. Read the actual expiry/scope from doctor and the client's whoami. Collect the final result, retry install after a partial registration failure, then reload clients. Verify the replacement before revoking the old key; revoke immediately if compromised.

ActionLocal resultServer access
uninstallRemoves unchanged recorded launcher entries; keeps credentialsKeys remain valid
logout / disconnectRemoves integration and clears both local MCP/REST credentials; project staysRevoke each credential separately in Dashboard
reset --client codex --installLogout, new pairing and registrationOld keys remain valid until revoked

Inspect the terminal result: modified entries or failed OpenCode removal remain for retry. Installation preserves unrelated MCPs, disabled/conflicting entries and private backups. Higher-precedence project configs can hide a global entry; inspect them before explicitly migrating Ordering. Do not delete other servers or restart shared services. Read the quickstart troubleshooting guide.

Alternative from your own terminal​

The prompt above follows SETUP.md. To run the same flow yourself, review the global configuration scope first and use a stable installation location:

git clone https://github.com/Ordering-co/ordering-dev-quickstart.git ~/ordering-dev-quickstart
cd ~/ordering-dev-quickstart
./ordering login start --client codex --install
./ordering login wait
./ordering doctor
./ordering clients

Use --client claude to identify Claude Code. If the checkout already exists, update it there with git pull --ff-only instead of cloning over it. Collect the final result and verify a call inside the client; global registration does not prove every app.

Quickstart and the optional plugin are public in the Ordering-co organization; cloning and marketplace installation do not require GitHub membership. Connecting to project data requires your own eligible Ordering account and consent. MCP can also use the manual alternative without cloning either repo.

MCP server contract​

Every Ordering.co project uses its own MCP Server URL. Copy the complete URL from the Dashboard; its canonical format is:

https://api.ordering.co/mcp/YOUR_PROJECT_CODE

Replace YOUR_PROJECT_CODE with the actual project code. The hostname is api.ordering.co and the path includes /mcp/ followed by that project code. There is no shared projectless endpoint. The client sends the personal MCP key as Authorization: Bearer ${ORDERING_MCP_KEY} through Streamable HTTP. Keep the key in the helper's private environment or a secret manager, and preserve environment references in client configs. A REST API key in X-Api-Key is a different credential for REST requests.

Manual alternative​

Use this when browser pairing or repository access is unavailable, or when you need a client-specific configuration. The steps below require a private shell environment and do not configure an already running desktop process.

Before you start​

  • Use a project and data you are authorized to access. Prefer a non-production project for your first connection.
  • Install Claude Code or Codex, and complete that client's own sign-in separately.
  • For this manual method, use a Bash or Zsh terminal and start the assistant from that terminal so it inherits the environment variable. The quickstart launcher above does not need that shell export.
  • MCP must be enabled for your project. The Dashboard shows whether it is available; a sample server URL does not enable it.
Who can create a key from the Dashboard?

The Settings route currently requires an administrator (level 0). The MCP server also supports enabled business managers (level 2), but that does not give them access to the Settings route. If you cannot open Settings, ask your project administrator about access; do not use another person's key.

1. Open MCP and create your key​

  1. Sign in to the Dashboard MCP settings and confirm the selected project. You can also navigate through Settings → Apps & developers → API & integrations → MCP (Claude Code & Codex).
  2. Coming soon means the project has MCP disabled. When MCP is enabled, the panel shows Server URL, Your MCP keys and connection instructions. If the status fails to load, use Retry before checking with your administrator.
  3. Copy the Server URL shown on the page. It is specific to your project. The setup guide in the Dashboard already includes this URL.
  4. Under Your MCP keys, select Create key, enter a descriptive name, and choose an expiration. The current default is 7 days and the maximum is 365 days; use the options shown by your project.
  5. Choose read for this walkthrough. If write is offered, it also includes reads but permits supported changes. Grant it only when those changes are needed.
  6. Read and accept the data notice before creating the key. Data the assistant reads is sent to its AI provider; use only data you are authorized to share with that provider.
  7. Copy the key into an approved secret manager. The full value is shown only once. Close the dialog when you have saved it securely.

The panel lists keys owned by the signed-in user and shows whether each is active, expired or revoked. They do not let the assistant bypass project, role, or resource permissions, and they cannot authenticate direct REST API calls.

2. Make the key available to the client​

In Bash or Zsh, run these lines and paste your key only at the hidden prompt:

printf 'MCP key (hidden): '
read -r -s ORDERING_MCP_KEY
printf '\n'
export ORDERING_MCP_KEY

This avoids putting the key in a command or shell history. The variable lasts for this shell session and its child processes. Repeat this step in a new terminal or after replacing a key.

Never put the real key in .mcp.json, config.toml, command arguments, screenshots, tickets, or version control. If you use a shell profile for persistence, remember that it stores the value in plaintext: keep it private and out of repositories and shared backups, or use your approved secret manager instead.

3. Configure your assistant​

In every example, replace https://api.ordering.co/mcp/YOUR_PROJECT_CODE with the complete Server URL copied from the Dashboard. Keep the environment variable reference unchanged. Choose the config-file method or the CLI method for your client, not both.

Claude Code​

Create or update .mcp.json at the root of your local project. If it already has other servers, add ordering without replacing them:

{
"mcpServers": {
"ordering": {
"type": "http",
"url": "https://api.ordering.co/mcp/YOUR_PROJECT_CODE",
"headers": {
"Authorization": "Bearer ${ORDERING_MCP_KEY}"
}
}
}
}

Alternatively, from that project folder:

claude mcp add --transport http --scope project ordering \
https://api.ordering.co/mcp/YOUR_PROJECT_CODE \
--header 'Authorization: Bearer ${ORDERING_MCP_KEY}'

Keep the single quotes around the header. They preserve the variable reference so Claude Code expands it when connecting, instead of saving the secret in the configuration.

Start claude in that folder from the terminal where you exported the key. Review and approve the project MCP server when prompted, then run /mcp inside Claude Code to check its connection. Adding the configuration alone does not prove the server is reachable.

Codex​

Add this table to ~/.codex/config.toml, or to .codex/config.toml in a trusted project. Update an existing ordering entry rather than adding a duplicate table:

[mcp_servers.ordering]
url = "https://api.ordering.co/mcp/YOUR_PROJECT_CODE"
bearer_token_env_var = "ORDERING_MCP_KEY"

Alternatively:

codex mcp add ordering \
--url https://api.ordering.co/mcp/YOUR_PROJECT_CODE \
--bearer-token-env-var ORDERING_MCP_KEY

bearer_token_env_var is the name of the variable, not its value. Codex reads it and sends the key as a bearer token.

Run codex mcp list to confirm registration. Start codex from the same terminal and use /mcp to inspect the server. Listing an entry is not a successful authenticated request; complete the checks below. If you use the IDE extension, its process must also receive the environment variable.

These instructions cover Claude Code and Codex, not browser connectors in claude.ai or ChatGPT. Do not assume those connectors accept this bearer-key configuration or that this server offers an OAuth login flow.

4. Check the connection with real requests​

Ask your assistant:

Who am I in Ordering?

Confirm that it actually calls whoami and that the returned project, user, role, key scope, and expiration match your intended connection. Do not share the raw response: it contains personal and project information.

Then ask:

List the last 5 orders

The assistant should discover the relevant operation and read the latest orders within your permissions. An empty list can be valid; it does not mean authentication failed. Ask it to minimize customer information and do not publish the results as setup evidence. Neither prompt requires write access.

Tools and API coverage​

ToolPurpose
whoamiIdentify the project, user, role, key scope, and expiration used by the connection.
search_operationsFind catalog operations available to your role and key scope.
describe_operationInspect an operation's inputs, including the allowed fields for a write.
read_operationRun a supported read operation with your permissions.
write_operationRun an explicitly supported write with allowed fields. Only available to keys with the write scope.

Use discovery rather than guessing operation IDs or sending arbitrary API paths. The API still authorizes every operation and resource. A write key does not unlock all REST endpoints or all fields of a supported operation. DELETE and file downloads are not exposed by this MCP catalog; writes outside the catalog, including financial changes such as refunds, are not enabled by selecting write.

Keep the client's approval step enabled for each write. Changes can trigger operational effects such as notifications and webhooks. After a timeout or server error on a write, read the affected record before retrying; do not assume a retry is deduplicated.

Use the API Reference for direct REST integrations and their authentication, not to infer MCP availability. For the commercial overview, see API & MCP.

Replace or revoke a key​

For quickstart installations, renew with ~/ordering-dev-quickstart/ordering login --install, collect the complete installer result, reload running clients, and verify whoami again. Read the actual expiration from doctor or whoami; do not assume every project uses the default. ./ordering uninstall removes unchanged launcher-owned registrations while preserving credentials. ./ordering logout removes those registrations and clears both local MCP/REST credentials, but does not revoke the remote key: revoke each key separately in the Dashboard when disconnecting.

  • Before a key expires, create a replacement in the same project's MCP settings. An expired key can offer Create a replacement with its name and scope prefilled; the replacement is a new key, not an extension of the old one.
  • Update ORDERING_MCP_KEY in the process environment and restart the assistant so it receives the new value. Check whoami again.
  • Revoke the old key once the replacement works. If a key is compromised, revoke it immediately rather than waiting for a replacement.
  • To disconnect, revoke the key in the Dashboard and remove the client's server entry. unset ORDERING_MCP_KEY clears this terminal's variable, but does not revoke the key or clear it from already running clients.

Troubleshooting​

SymptomWhat to check
Settings cannot be opened, or MCP is unavailableConfirm administrator access and project availability. Do not bypass the route or borrow another user's key.
Missing environment variableExport it in the terminal that launches the client, then restart the client. Do not print the secret to check it.
401, invalid or expired tokenUse an MCP key from the same project, not an API key/JWT. Replace an expired or revoked key; an older key without data-notice acceptance also requires replacement.
403The key owner must remain enabled and eligible. The API can separately deny an operation or resource. Requests with a browser Origin header are not accepted by the MCP endpoint.
404Recopy the project URL and confirm MCP is enabled for that project. A URL alone does not establish availability.
405 when opening the URL in a browserMCP is a POST transport, not a web page. Connect through the client instead of testing with a browser GET.
No write_operation, or an unknown operationCheck the key scope and discover available operations. Not every API operation is in MCP.
Validation errorInspect describe_operation and send only supported parameters and fields.
Rate limit, timeout, or API unavailableRespect rate limits and retry reads later. For uncertain writes, check the record before retrying.

If a client rejects a command, inspect claude mcp add --help or codex mcp add --help and compare the installed version with the current Claude Code MCP documentation or Codex MCP documentation. When requesting support, share only the client version and sanitized error, never a key, authorization header, or customer response.