Connect Claude Code or Codex with 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.

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.
Use a Bash or Zsh terminal for the commands below. Start the assistant from the same terminal so it inherits the environment variable.
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

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).
If the page says MCP is not yet available, confirm project availability with your administrator before continuing.
Copy the Server URL shown on the page. It is specific to your project. The setup guide in the Dashboard already includes this URL.
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.
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.
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.
Copy the key into an approved secret manager. The full value is shown only once. Close the dialog when you have saved it securely.

Your keys belong to your user. 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

Tool	Purpose
`whoami`	Identify the project, user, role, key scope, and expiration used by the connection.
`search_operations`	Find catalog operations available to your role and key scope.
`describe_operation`	Inspect an operation's inputs, including the allowed fields for a write.
`read_operation`	Run a supported read operation with your permissions.
`write_operation`	Run 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

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

Symptom	What to check
Settings cannot be opened, or MCP is unavailable	Confirm administrator access and project availability. Do not bypass the route or borrow another user's key.
Missing environment variable	Export it in the terminal that launches the client, then restart the client. Do not print the secret to check it.
`401`, invalid or expired token	Use 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.
`403`	The 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.
`404`	Recopy 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 browser	MCP 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 operation	Check the key scope and discover available operations. Not every API operation is in MCP.
Validation error	Inspect `describe_operation` and send only supported parameters and fields.
Rate limit, timeout, or API unavailable	Respect 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.

Before you start​

1. Open MCP and create your key​

2. Make the key available to the client​

3. Configure your assistant​

Claude Code​

Codex​

4. Check the connection with real requests​

Tools and API coverage​

Replace or revoke a key​

Troubleshooting​