Authenticate an MCP client

Connect an MCP host to Orderboost with native OAuth or the local companion, then authorize protected cart and checkout tools.

Connect your Model Context Protocol (MCP) host directly when it supports remote MCP OAuth. Use the local orderboost-mcp companion when the host can run a standard-input and standard-output (stdio) server but cannot complete remote OAuth.

Orderboost supplies the MCP resource URL and account origin for your integration. You do not need a local Orderboost API or a copy of the Orderboost repository.

Choose an authentication mode

Use one mode for each MCP connection:

Mode	Choose it when	Browser authorization
Native remote OAuth	Your MCP host supports OAuth discovery, callbacks, and Proof Key for Code Exchange (PKCE)	Your host opens its callback-bound authorization URL
Local companion	Your MCP host can launch a stdio command	`orderboost-mcp` returns an authorization URL in the tool result

Prefer native OAuth when your host stores tokens in an isolated credential broker. The companion stores tokens in a local file that only the current operating-system user can read.

Connect with native OAuth

Add the HTTPS MCP resource supplied by Orderboost to your host:

https://mcp.orderboost.example/mcp

Call an anonymous catalog tool to confirm the connection. When you first call a protected cart or checkout tool, Orderboost returns an OAuth challenge.

Use your host’s Authenticate action. The host adds its callback, state, and PKCE challenge before opening the browser. Orderboost cannot create that client-specific URL in advance.

Install the local companion

Install the companion on the machine that runs your MCP host:

npm install --global @orderboost/mcp-companion
orderboost-mcp --help

The orderboost-mcp command must be available in the environment that launches the host. Configure it with the MCP resource URL and account origin supplied by Orderboost.

[mcp_servers.orderboost]
command = "orderboost-mcp"
args = [
  "--url", "https://mcp.orderboost.example/mcp",
  "--account-origin", "https://account.orderboost.example"
]

{
	"mcp": {
		"orderboost": {
			"type": "local",
			"command": [
				"orderboost-mcp",
				"--url",
				"https://mcp.orderboost.example/mcp",
				"--account-origin",
				"https://account.orderboost.example"
			],
			"enabled": true
		}
	}
}

{
	"orderboost": {
		"type": "stdio",
		"command": "orderboost-mcp",
		"args": [
			"--url",
			"https://mcp.orderboost.example/mcp",
			"--account-origin",
			"https://account.orderboost.example"
		]
	}
}

Restart or reload the MCP host after changing its configuration. Use a local command or stdio entry. An HTTP entry connects directly and does not expose the companion tools.

Complete companion authorization

The companion starts authorization when a protected Orderboost tool requires OAuth. You can also call begin_orderboost_auth.

Open the returned URL

Open the exact authorization URL from the MCP tool result.

Existing accounts enter their password. New accounts verify their email before creating a password.

Approve MCP access

Review the requested scopes, then choose Allow.

Copy the connection code

Copy the six-digit connection code from the final popup screen.

Finish the connection

Pass the code to complete_orderboost_auth, then retry the protected tool.

The connection code is not the email verification code:

Code	Enter it in	Purpose
Email verification code	Orderboost account form	Proves ownership of a new account email
Companion connection code	`complete_orderboost_auth`	Completes this local companion OAuth flow

The connection code works once and expires after 10 minutes. The companion combines it with a secret stored only in the local process.

Verify the active mode

Inspect the MCP tool list:

If begin_orderboost_auth and complete_orderboost_auth are present, the local companion is active
If both tools are absent, the host is connected directly and must use its native OAuth action

Catalog search and lookup do not require OAuth. Use the first protected operation to trigger authentication.

Troubleshoot authentication

Use these checks before starting another flow:

orderboost-mcp cannot start: run orderboost-mcp --help from the same environment that launches the MCP host
No companion auth tools: replace the HTTP connection with the local command configuration, or use native OAuth
Connection code rejected: call begin_orderboost_auth again and use the new final-screen code
Email code rejected by complete_orderboost_auth: finish account verification in the browser, then copy the separate connection code
Authorization opens the wrong Orderboost environment: compare the configured MCP and account origins with the values supplied for your integration

Never ask a person to paste a password, OAuth token, client secret, or email verification code into chat.