> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Alvys MCP server for AI agents
> Connect AI agents directly to Alvys through the Model Context Protocol (MCP) server — a governed, authenticated gateway to the Alvys Public API.
Integrate Alvys capabilities using the **Model Context Protocol (MCP)** server.
The MCP server provides a set of tools that AI agents can use to interact with the Alvys APIs. You can use the MCP tools as a **developer** wiring an assistant into your workflow, as a **business owner** looking for financial insights or operational data, or as a **platform** connecting your own agents to perform tasks across dispatch, tracking, and settlement.
Unlike raw API integration, the MCP server gives your AI client a single, discoverable, and permissioned surface. Every tool call is authenticated with your Alvys credentials, scoped to your tenant, and audited — so agents get exactly the access you grant them, and nothing more.
**Internal Beta**
The Alvys MCP server is currently in **beta**. Access is granted on request — contact your account representative (existing customers) or the Alvys Partnership team (ISVs). During beta, the server exposes **read-only** tools.
## What is MCP?
Model Context Protocol is an open standard that gives AI assistants a live connection to external tools and data. Think of it like a USB port for AI — instead of pasting data into a chat window, your AI client connects directly to Alvys and can search, read, and (where permitted) act on your operational data in real time.
The Alvys MCP server sits in front of the [Alvys Public API](/docs/getting-started). It adds the safety properties an AI tool surface requires:
* **Authentication** — every request carries an Auth0 bearer token; unauthenticated calls are rejected.
* **Tenant isolation** — your company is resolved from the token itself, never from agent input.
* **Per-tool permissions** — each tool requires a specific scope (for example `load:read`), enforced on every call.
* **Read / Write / Destructive classification** — write and destructive tools are gated and off by default.
* **Auditing & rate limits** — every tool call is logged and throttled.
## Who it's for
| You are… | Use MCP to… |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| A **developer** | Give Claude, Cursor, or a custom agent live access to loads, trips, drivers, and carriers without hand-writing API calls. |
| A **business owner / ops** | Ask an AI assistant natural-language questions about your operation — open loads, invoice status, driver availability, tracking history. |
| A **platform / ISV** | Connect your agents to Alvys to automate dispatch, carrier onboarding, tracking, and settlement workflows. |
***
## Connecting to Alvys's MCP Server
The Alvys MCP server is a **remote MCP server** that speaks the MCP Streamable HTTP transport. You connect by pointing your MCP client at the server URL and authenticating with Auth0.
### Server URLs
| Environment | MCP Server URL |
| -------------- | --------------------------- |
| **Production** | `https://mcp.alvys.com/mcp` |
### Protocol version support
**You do not need to pick a protocol version, and there is nothing to configure.** MCP clients and servers negotiate the revision automatically on connect, so your client uses the newest revision both sides understand.
The Alvys MCP server implements MCP revision **`2026-07-28`** and still accepts these earlier revisions:
| MCP revision | Supported | Notes |
| ------------ | --------- | -------------------------------------------------------------------------------------- |
| `2026-07-28` | ✅ | Current. Sessionless — the revision travels on each request. |
| `2025-11-25` | ✅ | Negotiated via the `initialize` handshake. |
| `2025-06-18` | ✅ | Negotiated via the `initialize` handshake. |
| `2025-03-26` | ✅ | Negotiated via the `initialize` handshake. |
| `2024-11-05` | ✅ | Negotiated via the `initialize` handshake. Deprecated by MCP, but still accepted here. |
**If your client works today, it keeps working.** Upgrading the server to `2026-07-28` did not drop support for any revision. You do not need to update your client, change your configuration, or migrate to a different URL.
Practical implications:
* **Older clients** — no action. Your client negotiates an earlier revision and behaves exactly as before.
* **Newer clients** — no action. Your client negotiates `2026-07-28` and gets the newer protocol features automatically.
* **The tools, scopes, and URL are identical across revisions.** The negotiated revision changes protocol mechanics, not what your agent can do.
If a client fails to connect, the protocol revision is very unlikely to be the cause — check authentication and organization selection first (see the two options below), then contact [support@alvys.com](mailto:support@alvys.com).
There are two ways to authenticate, depending on your client.
### Option 1 — Interactive login (recommended for AI apps)
Best for human-facing clients that support remote MCP servers with OAuth — **Claude**, **Claude Code**, **ChatGPT**, **Cursor**, and **Codex**.
You add the server URL once and your client discovers the login flow automatically via the server's OAuth metadata (`/.well-known/oauth-protected-resource/mcp`). No client secret is stored in your MCP client — the interactive flow uses OAuth 2.1 with PKCE.
#### Set up your AI tool
Pick your client below. Every path ends the same way: a browser window opens to the Alvys login where you sign in and, if prompted, select your **organization**. Your client exchanges that session for a token scoped to your company and permissions, and can then list and call any tool your account is permitted to use.
1. Go to [Connectors settings](https://claude.ai/settings/connectors).
2. Select **Add custom connector**.
3. Enter the connector details:
* **Name** — `Alvys`
* **URL** — `https://mcp.alvys.com/mcp`
4. Select **Add**, then complete the Alvys login when prompted.
5. In a chat, open the attachments menu (**+**) and enable the Alvys connector.
1. Add the server:
```bash theme={null}
claude mcp add --transport http alvys https://mcp.alvys.com/mcp
```
2. Run `/mcp` in Claude Code and select **alvys** to start the login. A browser window opens to the Alvys login on first use.
Custom MCP servers are configured in the ChatGPT desktop app.
1. Open **Settings → MCP servers → Add server**.
2. Fill in the server details:
* **Name** — `Alvys`
* **Type** — **Streamable HTTP**
* **URL** — `https://mcp.alvys.com/mcp`
3. Select **Save**, then **Restart**.
4. Select **Authenticate** and complete the Alvys login.
The ChatGPT desktop app, Codex CLI, and the Codex IDE extension share one config file (`~/.codex/config.toml`), so this setup carries across all three.
1. Open the command palette with Command + Shift + P (Ctrl + Shift + P on Windows).
2. Search for **Open MCP settings** and select **Add custom MCP**.
3. In `mcp.json`, add the Alvys server:
```json theme={null}
{
"mcpServers": {
"alvys": {
"url": "https://mcp.alvys.com/mcp"
}
}
}
```
4. Reload Cursor and complete the Alvys login when prompted.
1. Add the Alvys server to `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.alvys]
url = "https://mcp.alvys.com/mcp"
auth = "oauth"
```
2. Start the login flow:
```bash theme={null}
codex mcp login alvys
```
A browser window opens to the Alvys login. Codex stores the resulting credentials and reuses them on later runs.
### Option 2 — Machine-to-machine (headless automation)
Best for **server-to-server agents** and back-end automation with no human in the loop. This flow reuses the same OAuth 2.0 **client-credentials** mechanism as the Alvys Public API.
1. Create (or reuse) an Alvys API application in **Admin → API Access** to get a `client_id` and `client_secret`. Select the scopes matching the tools you intend to call. See [Authentication](/docs/authentication-1) for the full walkthrough.
2. Request an access token:
```bash theme={null}
curl --request POST \
--url 'https://auth.alvys.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"audience": "https://api.alvys.com/public/",
"grant_type": "client_credentials"
}'
```
3. Point your MCP client at the server URL and pass the token in the `Authorization` header:
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```
The token's `scope` claim determines which tools you can call, and its organization claim scopes every call to your company's data.
Your `client_id` and `client_secret` are sensitive. Store them securely and never expose them in front-end code. Tokens are scoped to exactly the permissions granted to your application.
### Verifying the connection
Once connected, ask your MCP client to **list available tools**, or issue an MCP `tools/list` call. You should see the Alvys tools grouped by domain (loads, trips, drivers, carriers, and more). For the full catalog, see [Available MCP Tools](/docs/available-mcp-tools).
A raw transport check (returns the server's tool list over Streamable HTTP):
```bash theme={null}
curl -sD - -X POST https://mcp.alvys.com/mcp \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
***
## Permissions & safety
The MCP server enforces the **same scope model** as the Public API. Each tool declares a required permission using the `{resource}:{action}` convention — for example `load:read`, `carrier:update`, or `tender:create`. A tool call fails if your token lacks the scope.
Tools are classified into three tiers:
| Tier | Examples | Availability |
| --------------- | ------------------------------------------------------------------- | -------------------- |
| **Read** | `loads_search`, `drivers_get_by_id`, `visibility_inbound_history` | Always available |
| **Write** | `tenders_create`, `trips_assign`, `invoices_record_carrier_payment` | Disabled during beta |
| **Destructive** | cancel / void actions | Disabled by default |
Additional guardrails applied to every call:
* **Tenant isolation** — your company is derived from your token's organization claim; agents cannot target another tenant.
* **Rate limiting** — per-token request throttling protects your account and the platform.
* **Response size caps** — oversized responses are rejected to keep results within an AI client's context window.
* **Audit logging** — every tool call is recorded with the caller, tenant, and trace id.
## Guided prompts
Beyond individual tools, the server ships **guided prompts** — multi-step workflows an agent can follow end to end:
| Prompt | What it does |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `find_and_cover_load_v1` | Find an open load and cover it with a carrier via a tender. |
| `dispatch_driver_v1` | Check driver availability (including an 8-day ELD lookback for the federal 70-hour/8-day HOS window) and assign a driver, truck, and trailer to a trip. |
| `carrier_onboarding_v1` | Look up a carrier by MC/DOT, review documents, upload the packet, and activate. |
| `settlement_reconciliation_v1` | Reconcile a load's invoices, deductions, and carrier/customer payments. |
| `track_shipment_v1` | Pull inbound and outbound tracking history for a shipment. |
## Next steps
Browse the full catalog of tools, grouped by domain, with the scope each one requires.
Full walkthrough of creating credentials and issuing access tokens.
New to the Alvys API? Start here.
**Need access or help?**
* Existing Alvys customers: contact your account representative.
* ISVs / partners: contact the Alvys Partnership team.
* Technical support: [support@alvys.com](mailto:support@alvys.com)