Connect bidrayl to your AI assistant

Ten minutes, one API key, no code. Once connected, your assistant can quote lanes, look customers up, log calls, raise follow-ups and produce customer documents — using your own bidrayl account, your own rates and your own subscription.

The connection runs over the Model Context Protocol (MCP), an open standard for giving an assistant real tools instead of screenshots and copy-paste. If you want the argument for why this is worth doing before the mechanics, read what MCP gets you.

What you need
A bidrayl account Any plan. What the assistant can quote depends on your plan — see plans
A private API key From Settings → API keys in the dashboard. It starts with dk_
An MCP-capable assistant Claude (web, desktop or Code), ChatGPT, Cursor, or anything else that speaks MCP

The server address you will paste:

https://api.bidrayl.com/mcp

Step 1 — create an API key

  1. Log in to app.bidrayl.com and go to Settings → API keys.
  2. Click Create API key, name it after the assistant you are connecting ("Claude desktop", say), and leave the type as private.
  3. Copy the secret. It is shown once — we store only a hash and cannot show it again. If you lose it, revoke the key and make another.

Treat that key like a password. It can quote, read and write your CRM, and generate documents on your behalf. It cannot manage users or change your subscription.

Step 2 — add the connector

Pick your assistant. In every case you are pasting the same URL and then pasting your API key into a login form.

Claude (web and desktop)

  1. Open Settings → Connectors and choose Add custom connector.
  2. Paste https://api.bidrayl.com/mcp as the server URL and save.
  3. Click Connect on the new bidrayl connector. A bidrayl login page opens.
  4. Paste your dk_… API key and submit. The window closes and the connector shows as connected.
  5. Start a new chat. The bidrayl tools are now available to Claude.

Claude Code

claude mcp add --transport http bidrayl https://api.bidrayl.com/mcp

Then run /mcp inside Claude Code and authenticate — same paste-your-key login. Add --scope project to share the connector with a repo via .mcp.json, or leave it off to keep it to your user account.

ChatGPT

Under Settings → Connectors, add a custom connector with the same URL and complete the same login. Connector support varies by plan and is a moving target on OpenAI's side; if you do not see the option, that is why.

Cursor, Windsurf, and other clients

Anything that supports remote MCP servers over HTTP works. Point it at https://api.bidrayl.com/mcp; the client will discover the login flow. A config file usually looks like this:

{
  "mcpServers": {
    "bidrayl": {
      "url": "https://api.bidrayl.com/mcp"
    }
  }
}

Step 3 — check it works

Ask your assistant something only bidrayl can answer:

Quote a 53-foot container from 60601 to 90001 shipping next Tuesday, ramp-to-ramp.

You should get a routed quote with the dray, rail and dray legs priced separately. If instead you get a plan error, the mode you asked for is not on your subscription — see below.

A good second test, because it proves the write path and the CRM link:

File that quote against Acme Distribution and set me a task to follow up on Thursday.

How the login works

There is no bidrayl password in this flow, by design.

The connector uses OAuth 2.0 with PKCE, but instead of a password step you paste your API key, and that key becomes the access token. Your assistant sends it as a bearer token, and each tool call re-authenticates against the bidrayl API with it. The key identifies your tenant, so the assistant only ever sees your own data.

Nothing is stored on the MCP server except short-lived, single-use authorization codes (five minutes) used to complete the handshake. Revoking the key in Settings → API keys cuts the assistant off immediately — that is the off switch.

What your plan allows

The assistant is told which plan each quoting tool needs, so it can explain a limit rather than failing cryptically.

Capability Plan
CRM, quote history, documents Every plan
Door-to-door quoting Starter and up
Ramp-to-ramp and combined quoting, per-diem edits Pro and up
Bulk lane pricing Business

When a call is outside your plan, the API answers feature_not_entitled and the assistant is instructed not to retry, but to tell you which plan the feature needs.

What the assistant can do

45 tools, grouped the way the product is:

  • Quoting — door-to-door (all carriers at once, or one at a time), ramp-to-ramp, combined, bulk lanes, and per-diem adjustment.
  • Quote history — list, read and delete past quotes across every mode.
  • Customer documents — generate a customer-facing quote PDF and fetch it again later.
  • Companies and contacts — create, search, read, update, delete.
  • Deals — open an opportunity, move it through the pipeline, read the board by stage.
  • Activities and tasks — log what happened, raise and complete follow-ups, see what is due today or overdue, and file either against a deal.
  • People — resolve a colleague's name to the user id a task assignment needs.

Three things are deliberately not exposed: the Excel bulk export, the raw PDF bytes and deal attachments, because the transport carries text rather than files. Ask for a bulk quote and you get the priced lanes as data; ask for a document and you get its id and reference, which the dashboard can download.

CRM automation

Twenty-nine of the 45 tools are CRM, which is where the hours actually go. Each recipe below is one ask; the tools it fires are named so you can see exactly what the assistant is doing on your behalf.

Ask for What happens Tools
Log a call — "spoke to Dana at Acme, wants weekly SAV→DFW, remind me Thursday" The activity is logged against the company with the person it was with, and the follow-up is raised. A contact who isn't on file gets created create_activity, create_contact, create_task
File a quote — "file that quote against Acme and give me the PDF reference" The quote lands on the customer's timeline, and the customer document is generated create_activity, create_quote_pdf
Brief me — "what do we know about Acme? I'm on with them at three" Account, people, recent history and every quote filed against them, as one brief search_companies, list_company_contacts, list_activities, list_quote_history
Clear follow-ups — "what's overdue? close the two I handled, push the rest to Monday" Triage, complete and reschedule in one pass. Assign by name and the person is resolved for you get_tasks_overdue, get_tasks_due_today, update_task, list_assignees
Fix the data — "find every prospect we've quoted twice and mark them active" Statuses, payment terms, tags, preferred lanes and equipment brought up to date list_companies, update_company, update_contact
Summarise — "what intermodal opportunities did we log this month, and which went nowhere" The activity log read back as a summary, filtered by mode, outcome, account or date list_activities, list_quote_history
Open an opportunity — "open a Q1 bid for Acme, 40 loads a week, owed back the 1st" A deal on the pipeline with its volume, type and due date create_deal
Move the pipeline — "move the Acme bid to awaiting review" / "we won it" The stage changes; winning or losing stamps the close date update_deal, list_deals
Review the board — "how does the pipeline look for Dana?" A count per stage, every stage present, filtered however you asked get_deal_pipeline
One opportunity's whole story — "everything we've done on the Acme bid" Every activity and task filed against that deal, plus where it stands get_deal, list_activities, list_tasks

How a quote reaches a customer's record

Every quote a tool returns carries a quote_history_id — the same number the dashboard shows on a history row — and that single id does everything downstream, for door-to-door, ramp-to-ramp and combined alike.

There is no "assign quote to customer" call, on purpose. A quote becomes that customer's quote when an activity carrying that id is logged on the company, or when a customer PDF is generated naming the company. Both count, so the customer's quote list is the union of the two — the ones that became a document and the ones that did not.

That is why "file this against Acme" works: the assistant logs the activity with the id, and the quote appears on the account.

Assignment needs a name

An API key belongs to your company rather than to a person, so a task created through the connector has no implicit owner and stays unassigned unless you say who it is for. Name the colleague — "assign it to Dana" — and the assistant resolves them to a user id with list_assignees.

Deals, and the one flag that lies

The pipeline runs PROSPECTING → QUOTING → AWAITING_REVIEW → WON | LOST. Reaching a terminal stage stamps the close date; moving back into the pipeline clears it. Activities and tasks both take a deal, which is what makes "everything we did on this opportunity" a single question.

Deleting a deal keeps the history — its activities and tasks survive, unfiled. If you mean "this went nowhere", ask to set the stage to LOST instead; that keeps the opportunity on the record.

One wrinkle worth knowing, because it would otherwise mislead you: there is no "closed only" filter. Asking for active deals narrows to the ones still in the pipeline, but the opposite is not a filter — for closed ones, ask for the WON and LOST stages by name. The assistant is told this, so it should get it right without your help.

What the connector can't do to your CRM

Worth knowing before you promise it to a colleague:

  • Deal attachments are not exposed. Opening and moving deals works, but uploading or downloading RFP paperwork is a file transfer the text transport cannot carry.
  • A logged activity can't be edited or deleted through the connector — only created and listed. Corrections go through the dashboard.
  • There is no single-box search across every CRM record over MCP; companies and contacts each have their own search.
  • Writes are one record at a time. "Update forty accounts" is forty calls, which works but is not instant.

Everything in that list exists in the REST API. If you want it in the connector, tell us — that is how this list gets shorter.

Troubleshooting

The login page never appears, or the connector errors immediately. Check the URL has the /mcp suffix and no trailing slash: https://api.bidrayl.com/mcp.

"Unauthorized" on every tool call. The pasted key was a public (pk_) key, or has been revoked. Public keys reach the quote widget only. Create a private key and reconnect.

The assistant says a feature needs a higher plan. It does — see what your plan allows. This is not a connection problem, and retrying will not help.

Quotes take a while. Door-to-door quoting calls each carrier's own API and waits, so it is as slow as the slowest carrier. Ramp-to-ramp is priced on our side and comes back far faster. If you are impatient, ask for ramp-to-ramp.

A task came back unassigned. An API key belongs to your company rather than to a person, so an assignment has no implicit owner. Name the colleague and the assistant will resolve them to a user id.

You want to cut access off. Revoke the key in Settings → API keys. The assistant loses access on its next call; no need to remove the connector first.

Is it safe?

The honest answer is that it is exactly as safe as the key you paste, and you control that.

  • The key scopes to your tenant only. The assistant cannot see another broker's customers, rates or quotes.
  • It carries member rights: it can quote, write CRM records and generate documents. It cannot manage users, change billing, or reach any operator-level function.
  • Records an assistant creates are attributed to the key, not to a person, so an agent's note stays distinguishable from one your rep typed.
  • Revocation is immediate and one click.

If you would rather the assistant could only read, that is not expressible with a single key today — tell us, because it is the most-asked-for refinement and we would build it against real demand.

The same thing, in code

MCP is for assistants. If you are wiring bidrayl into a TMS or your own service, use the REST API directly — same account, same key, no connector: API reference.

One key, and your assistant
starts quoting.

Create an account, generate a private API key, and paste it into the connector. Everything above works on any plan — quoting scope follows your subscription.

Create an account Why MCP?