# Agent CLI and MCP

The TractionScout Agent CLI lets external agents, local scripts, cron jobs,
and CI work through TractionScout's API. The server retains connector
credentials, project permissions, approval policy, audit records, memory,
and quota tracking.

## Availability and setup

Use the CLI package or repository checkout provided for your deployment and
follow its Node.js requirements. Public package distribution may not yet be
available during pre-release. If you already have a TractionScout checkout
containing `agent-cli`, install from the repository root:

```bash
npm install -g ./agent-cli
tscout --help
```

Obtain a dedicated TractionScout user access token authorized for the
project. Your workspace administrator can help with token access. Set the
API URL, token, and project ID in your local environment or automation's
secret configuration:

```bash
export TRACTIONSCOUT_API_URL=https://tractionscout.com
export TRACTIONSCOUT_API_TOKEN=your_user_access_token
export TRACTIONSCOUT_PROJECT_ID=your_project_id
```

Replace the example token and project ID with your values. For another
deployment, use its base URL. Keep tokens out of prompts and source files.

## Discover before preparing work

```bash
tscout auth:status
tscout projects:list
tscout integrations:list "$TRACTIONSCOUT_PROJECT_ID"
tscout capabilities:execution "$TRACTIONSCOUT_PROJECT_ID"
```

`auth:status` verifies the configured token with the server; `projects:list`
shows the projects it can access. Inspect the execution capabilities before
choosing tools or asking an agent to act.

When the project has suitable evidence and you intend to start an agent run:

```bash
tscout agents:orchestrate "$TRACTIONSCOUT_PROJECT_ID" \
  --prompt "Review the connected evidence and stage a useful next growth move."
tscout actions:list "$TRACTIONSCOUT_PROJECT_ID" --status queued
```

Agent runs use the project's configured AI resources and budget. The
orchestration response returns a durable `run_id`; inspect it with
`tscout agents:status "$TRACTIONSCOUT_PROJECT_ID" "$RUN_ID"`. Review the
staged work and applicable approvals before execution. Commands return JSON;
`--compact` produces single-line output for automation.

## Connecting through MCP

The execution-capabilities response includes the deployment's MCP descriptor.
Use that descriptor to configure a compatible client with the TractionScout
bearer token. The default mode blocks user-authored staging; the
`review_staging` mode additionally allows supported internal review
artifacts. All MCP modes block external execution.

Some reads, including explicit keyword research, can incur provider charges
and persist evidence. Check tool annotations and requested budgets before
calling them. Provider credentials remain in the server-side integration.

See [Connecting your data sources](/docs/integrations.html) and
[Getting started](/docs/getting-started.html) for the project setup behind
these workflows.