> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withterminal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Give coding agents access to Terminal fleet data through MCP or the Terminal CLI. Both are in beta.

<Warning>
  Terminal's agent tools — the MCP server and the CLI — are in **beta**. Tool
  names, commands, and arguments may change.
</Warning>

You can give an agent the same Terminal data you already query from the [Terminal API](/api-reference): connections, vehicles, drivers, locations, HOS, safety events, and more. Anything you can read from the API, an agent can read through these tools.

There are two beta interfaces. Use whichever fits how the agent already works.

|          | [MCP server](#mcp-server)                    | [CLI](#cli)                                   |
| -------- | -------------------------------------------- | --------------------------------------------- |
| Best for | Cursor, Claude, and other MCP clients        | Shells, scripts, and agents that run commands |
| Auth     | Sign in with your Terminal Dashboard account | A Terminal secret key (`sk_…`)                |
| Install  | Add the MCP URL to the client                | `npm install -g @terminal-api/cli`            |

Neither replaces the Terminal API. Use that when you are building a product integration.

## MCP server

The MCP server exposes Terminal API operations as MCP tools. Add the URL to your client and sign in with your Terminal Dashboard account when the browser opens. You do not put a secret key in the client config.

```
https://mcp.withterminal.com/mcp
```

The server uses [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) and OAuth. The client must support both.

### Connect a client

Every MCP client adds remote servers a little differently. In general:

1. Find the MCP or connectors settings in your client (for example, **Cursor Settings → MCP**, or **Settings → Connectors** in Claude).

2. Add a remote server with the URL `https://mcp.withterminal.com/mcp`. Some clients take a JSON config instead:

   ```json theme={null}
   {
     "mcpServers": {
       "terminal": {
         "url": "https://mcp.withterminal.com/mcp"
       }
     }
   }
   ```

3. When prompted, sign in with the Terminal Dashboard account that should access your applications.

4. Confirm Terminal tools such as `listApplications` and `listVehicles` appear.

Check your client's documentation for the exact steps.

### Scope

What the agent can see matches your Dashboard user: applications in your active organization, and the connections and data that user can read. Tools take an application ID and, where relevant, a connection token as arguments; the tool descriptions tell the agent how to resolve them, so you rarely need to supply them yourself. Secret endpoints such as application keys are not exposed.

## CLI

The [Terminal CLI](https://github.com/terminal-api/terminal-cli) is an open-source command line for the same API, published as [`@terminal-api/cli`](https://www.npmjs.com/package/@terminal-api/cli). Agents can run `terminal` commands, or you can use it yourself in a shell.

### Install

```bash theme={null}
npm install -g @terminal-api/cli
```

`pnpm add -g @terminal-api/cli` and `bun install -g @terminal-api/cli` also work.

### Configure

```bash theme={null}
terminal config set api-key sk_prod_xxx
terminal config set connection-token con_tkn_xxx
```

You can also use environment variables (`TERMINAL_API_KEY`, `TERMINAL_CONNECTION_TOKEN`) or [profiles](https://github.com/terminal-api/terminal-cli#profiles) for sandbox vs production.

Get a secret key from the [Dashboard](https://dashboard.withterminal.com/api-keys). Connection tokens come from [list connections](/api-reference/connections/list-connections) or the consent flow.

### Use

```bash theme={null}
terminal list-connections --format table
terminal list-vehicles --format table
```

Commands map to Terminal API operations in kebab-case. Run `terminal --help` for the full list, or `terminal` with no arguments for an interactive TUI.

The repo also ships [agent skills and commands](https://github.com/terminal-api/terminal-cli/tree/main/ai) you can copy into your agent so it knows how to call the CLI.

## What agents can query

MCP tools and CLI commands cover the read side of the Terminal API: applications and connections, vehicles and locations, drivers and HOS, trips, safety events, and the rest. A few examples:

* `listVehicles` / `terminal list-vehicles`
* `listLatestVehicleLocations` / `terminal list-latest-vehicle-locations`
* `listHOSLogs` / `terminal list-hos-logs`

Ask the agent what tools it has, or run `terminal --help`, for the current list. For request and response fields, use the matching [API reference](/api-reference/authentication) page.

## Feedback

Please share feedback on how Terminal can better support your agents via our shared Slack channel or [support@withterminal.com](mailto:support@withterminal.com)