ARK MCP server

OAuth-connected broker tools for supported AI clients, limited by the connected ARK user and enabled operation policy.

Developer portal | MCP docs for agents | API docs | OAuth metadata

MCP quickstart

The ARK MCP server is in production preview. It connects an AI client to the same ARK identity, permissions, teams, and records a user already has. It uses Streamable HTTP and OAuth 2.1 Authorization Code with PKCE.

Server URL

https://arktms.com/api/agent/mcp

Your organization must be enabled for MCP. During OAuth, sign in with your normal ARK account and review the requested scopes. ARK never gives an MCP connection more access than that user has.

First conversation

After connecting, ask a normal operational question:

What's my current work queue and what needs attention first?

The client can discover and call ark_get_work_queue without you naming the tool. Follow with a specific load question, for example:

What's happening with load 1008, and is anything blocking billing?

Read-only tools run without an ARK approval request. Controlled writes use the approval flow described below.

Available tools

The generated reference contains the complete external preview catalog. Core preview connections emphasize context, search, work queues, customers, carriers, loads, tracking, billing readiness, approvals, and common dispatch actions. Expanded preview adds the remaining documented operational tools for enrolled organizations.

Internal tools are omitted. A client's tools/list is filtered by rollout tier, OAuth scopes, ARK permissions, and visible teams, so a connection normally receives fewer definitions than the reference.

Connect an MCP client

All supported clients use the ARK server URL and complete OAuth in a browser. Never paste an ARK password, API token, OAuth access token, or refresh token into client configuration.

ChatGPT

In ChatGPT web, an eligible workspace administrator or authorized developer must enable Developer mode and create a custom app from Settings > Apps. Enter the ARK MCP server URL, select OAuth, scan the tools, and complete the ARK authorization flow. Open a new conversation and select the draft or published app from the tools menu.

Full remote-MCP support, including ARK's controlled write tools, is currently a beta for Business, Enterprise, and Edu workspaces. Pro accounts can connect custom apps with read and fetch permissions, but should not be presented as supporting every available ARK tool. ChatGPT does not connect directly to a local MCP server; the production ARK URL is remote HTTPS.

Claude

In Claude or Claude Desktop, open Settings > Connectors, choose Add custom connector, name it ARK TMS, and enter the ARK MCP server URL. Select Connect and complete OAuth. Team and Enterprise workspaces may require an owner to add the organization connector before individual users can connect it.

Codex

Add the remote server, authenticate, and verify the connection:

codex mcp add ark --url https://arktms.com/api/agent/mcp
codex mcp login ark
codex mcp list

For manual configuration, add a [mcp_servers.ark] table with the ARK url to ~/.codex/config.toml or a trusted project's .codex/config.toml; OAuth is the default authentication mode for Streamable HTTP servers. Codex CLI, the Codex app, and the Codex IDE extension share this configuration.

Cursor

Add a project-scoped .cursor/mcp.json or global ~/.cursor/mcp.json entry:

{
  "mcpServers": {
    "ark": {
      "url": "https://arktms.com/api/agent/mcp"
    }
  }
}

Open Cursor's MCP settings, enable ARK, and complete the OAuth prompt. Cursor documents Streamable HTTP and OAuth support for remote servers. Use a current Cursor release if discovery or OAuth does not start.

Client references

• ChatGPT developer mode and MCP apps
• Codex MCP configuration
• Claude custom connectors
• Cursor MCP
• MCP authorization specification

OAuth, sessions, and approvals

Effective access

MCP access is the intersection of the current ARK user, organization membership, visible teams and entities, granted OAuth scopes, operation policy, and the enabled external-access tier. Scope step-up may be required when a tool needs a scope not granted during the initial read-only connection.

An insufficient scope returns HTTP 403 with an insufficient_scope bearer challenge. A compatible client can reauthorize for the requested scopes and retry. Request offline_access only when the client needs a refresh token.

The reference publishes every externally supported preview tool. tools/list is narrower: core workflow tools remain discoverable for OAuth step-up, while expanded tools are advertised only when the organization has expanded-preview access and the OAuth grant, user permissions, and team visibility allow them. This keeps unrelated tool definitions out of normal agent context without hiding the supported catalog.

Sessions

ARK uses stateful Streamable HTTP sessions. Clients initialize without a session header, retain the returned MCP-Session-Id, and send it with MCP-Protocol-Version: 2025-11-25 on later requests. Clients normally manage this protocol automatically.

Approval behavior

Tools marked as requiring an ARK approval request use a single-use, server-backed approval:

1. The client calls ark_create_approval_request with the supported operation ID and exact proposed input.
2. The connected user reviews and approves the request in ARK.
3. The client retries the same tool with the same normalized arguments and idempotency key.

The approval is bound to the user, organization, operation, tool, arguments, stable OAuth grant, and idempotency key. A host application's confirmation prompt is useful additional UX, but it is not ARK authorization. MCP tools cannot approve their own requests.

Idempotency

External writes require a stable idempotency key. ARK normally derives one from the authenticated session and JSON-RPC request ID. Exact retries must reuse that request ID. Advanced clients can set _meta["ark/idempotencyKey"]; caller-supplied keys are limited to 200 characters and cannot contain control characters.

Rate limits

OAuth MCP access tokens default to 300 requests per minute. API and MCP traffic shares an organization budget that defaults to 3000 requests per minute. Credential and organization policy can override those defaults. A 429 response includes rate-limit metadata and Retry-After.

Tool results and errors

Tools return the canonical operation result in MCP structuredContent and mirror it as JSON text content. Error results set isError: true and include a stable code, message, and optional details. Common codes include missing_scope, missing_permission, team_access_denied, validation_failed, approval_required, approval_not_found, idempotency_key_required, rate_limit_exceeded, and operation_not_available.

Broker workflows

MCP tools are designed for natural broker requests rather than requiring users to name individual calls.

Start the day

What's my current work queue and what should I handle first?

The agent can inspect the current context, retrieve the work queue, and follow relevant load identifiers while preserving team visibility.

Investigate a late load

What's the status of loads 1008 and 1010? They're running late.

The agent can search for each visible load, inspect stops, dispatch notes, and tracking status, then summarize facts without changing the records.

Review carrier risk

Is the carrier we're considering for load 1003 safe to use? Show me the risks, not a booking decision.

The agent can find the load and carrier and use the risk-card tool to summarize available signals. ARK does not turn those signals into an automatic booking decision.

Create a load

Create this Acme load from Chicago to Dallas for tomorrow in a dry van.

The agent should resolve the customer, team, and locations, gather any missing required fields, create an approval request for the exact load input, and execute ark_create_load only after ARK approval.

Cover a load

Cover load 1003 with the carrier from the accepted bid.

The agent should inspect the load and bids, confirm the selected active carrier and required dispatch contact details, create an approval request, and execute ark_assign_carrier only after approval.

Prepare billing follow-up

Which visible loads are waiting on POD review or blocked from billing?

The agent can combine the POD review queue with load billing-readiness results. Core preview connections can inspect blockers; expanded preview connections can also update POD review status, generate invoices, and send billing documents when the credential has the required access and the exact write receives ARK approval.

MCP tool reference

Browse 279 external preview tools. Each detail page is generated from MCP and operation metadata; internal tools are not published.