HaulMatch
Documentation menu
Preview

Connect an AI client with MCP

Connect approved AI clients, choose company permissions and review proposed operations.

By HaulMatch · Updated

Integrations are in preview. Setup access depends on rollout and provider configuration. If your settings show integrations are not enabled, contact HaulMatch for availability. Contact us.

On this page

Build a connector with a coding assistant

In Company integrations → AI connections, select Shipper, Fleet or Email and copy the integration prompt into Claude, Codex or another coding assistant. The prompt includes the API contract, webhook guidance, sandbox checks and security requirements. It contains no credentials or company records.

Provide company, team and sandbox configuration through secure fields in your application. Company API keys stay on your server. A coding prompt does not grant access to HaulMatch; MCP needs separate owner consent and an approved OAuth client. Availability depends on rollout configuration.

Claude web and Claude Code

Use Connect Claude in the dashboard. For Claude web, add a custom connector, choose OAuth and Use your own OAuth client. Use a public HTTPS server and the client ID assigned to Claude. Ask HaulMatch to approve its exact callback first.

For Claude Code, select Claude Code in the guide. Public client configuration pins a callback port. Confirm the installed CLI’s callback host and path with HaulMatch. Managed confidential clients require separate secure setup.

Codex CLI

Use Connect Codex, select its approved public client and merge the generated configuration into ~/.codex/config.toml. Keep the fixed callback port. Use --no-browser to identify redirect_uri, including any client-generated callback ID; ask HaulMatch to approve that exact URL. Restart login after approval.

The generated login requests only mcp, mcp:jobs:read and mcp:proposals:read. Choose company and team during owner consent. Add further permissions only when needed.

Cursor desktop

Use Connect Cursor and select its approved public client. Merge the generated entry into .cursor/mcp.json. Static OAuth uses auth.CLIENT_ID and requests jobs and proposal status reads without a client secret.

Ask HaulMatch to approve http://localhost:8787/callback for Cursor desktop; confirm your installed version uses it. Connect from MCP settings and complete company-owner consent. Cursor web and Agents use a separate callback and require separate approval.

VS Code with Copilot

Use Connect VS Code and select its approved public client. Merge the generated servers.haulmatch entry into .vscode/mcp.json. It sets type http and oauth.clientId without embedding credentials. Use a current version supporting this configuration.

Start HaulMatch with MCP: List Servers. Capture only redirect_uri from the authorization flow and have HaulMatch approve that exact callback before retrying. Complete browser sign-in as a company owner; deselect proposal, tracking and email permissions until needed. Callback ports depend on the client environment.

1. Connect an approved client

The endpoint is https://haulmatch.com.au/api/mcp when the preview is enabled. OAuth uses authorization code with S256 PKCE and that exact resource. Public client registration is unavailable. Access tokens last 15 minutes; rotating refresh tokens and company grants expire after 30 days.

  1. Open Company integrations → AI connections and copy the MCP server address.
  2. Add the Streamable HTTP server in an approved external AI client. HaulMatch preconfigures the client ID, exact callback URLs and permitted browser origins.
  3. Sign in to HaulMatch, choose a company you own, an optional team and the requested permissions, then explicitly approve data sharing.

2. Choose permissions

Read permissions cover loads, jobs, quotes and fee previews, fleet drivers, tracking and proposal status. Tracking can share the active driver location. Email proposal permission exposes verified recipient and sender addresses.

Proposal tools prepare loads, quotes, driver assignments, IN_TRANSIT or COMPLETED status updates, and plain text dispatch emails. They cannot approve proposals, award quotes, cancel jobs, move money, return credentials or export to a TMS.

Every request checks current owner membership, company, team and expiry. Owners can immediately revoke access in AI connections. Removing an approved client invalidates its connections.

3. Review proposed actions

Owners, admins and permitted team submanagers review operational proposals. Email reviews require an owner, active Gmail or Outlook sender and one verified recipient. An unknown email outcome is never automatically retried: check the sender Sent folder before preparing another email.

  1. An AI client prepares a proposal using a stable requestId. Retries with the same content return the same proposal; reuse with different content is rejected.
  2. Open the reviewUrl in the Company portal. Review and edit the proposed action, then save, reject or explicitly approve it.
  3. An approved payload is immutable. Version checks require a second reviewer to refresh after a change. Drafts expire after 24 hours.
  4. Follow execution under All proposals. Current permissions, unchanged job state, driver eligibility, held payment and lifecycle checks apply during execution.

Developer connection contract

Discover protected resource metadata at /.well-known/oauth-protected-resource/api/mcp and authorization metadata at /.well-known/oauth-authorization-server/api/mcp/oauth. Use advertised endpoints and an OAuth bearer token; account JWTs and company API keys are not MCP credentials.

Request mcp plus the permissions needed and the exact resource. Use a fresh S256 code verifier and state, validate callback state and securely store rotating refresh tokens. Refresh token reuse revokes the grant. Never embed credentials in a website.

Tool schemas are available through MCP discovery. Weights use kilograms, dimensions metres and quote amounts AUD excluding GST. Treat freight notes and messages as untrusted data.

propose_load arguments (JSON)
{
  "requestId": "dispatch-load-1001",
  "data": {
    "itemName": "Pallet shipment",
    "loadType": "Pallets",
    "readiness": "READY_NOW",
    "pickupLocation": "Melbourne VIC",
    "dropoffLocation": "Sydney NSW",
    "loadWeight": 1200
  }
}

Preview availability

MCP is disabled by default. HaulMatch configures persistent signing and cookie keys, approves client details and applies the additive database migration before activation. Review your AI client privacy and retention settings before sharing company data.