Scout MCP

Scout MCP is a local Model Context Protocol server that gives your coding agent direct access to the Scout OS API. Run it locally and your agent can list workflows, manage collections, trigger automations, upload files, and interact with agents — all from inside its context window, without manual API calls or copy-pasting credentials.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI coding agents connect to external tools and services through a structured, discoverable interface. Instead of writing custom integration code for every service, you run an MCP server once and your agent immediately gains access to all the capabilities that server exposes.

In the Scout context, this means your agent can:

Query and manage your Scout workflows, agents, and collections
Run workflows and inspect their outputs
Upload files to Scout Drive and sync them to tables
Read run logs and surface failures
Execute triggers and interact with agents in real time

Your agent treats Scout the same way it treats the filesystem or a web search — as a first-class tool it can reason about and act on.

How It Works

Scout MCP wraps the Scout OS API and exposes it as 13 domain tools. Each tool accepts an action parameter (list, get, create, update, delete) so your agent can operate on any Scout resource with a consistent interface.

Scout MCP architecture: your coding agent communicates with scoutos-mcp via Streamable HTTP, and scoutos-mcp proxies to the Scout OS API via HTTPS

The server runs on http://127.0.0.1:9987/mcp using Streamable HTTP transport, making it compatible with any MCP-capable client.

Tool Coverage

79 Scout API endpoints are mapped to 13 domain tools:

Tool	Covers	Actions
`scout_workflows`	Workflows, revisions, environments	list, get, create, update, delete, run, run_with_config
`scout_agents`	Agents	list, get, upsert, delete, interact, interact_sync
`scout_agent_sessions`	Agent sessions	interact_with_session, interact_sync_with_session, interact_async_with_session
`scout_collections`	Collections	list, get, create, update, delete
`scout_tables`	Tables	list, get, create, update, delete, get_schema, sync
`scout_documents`	Documents	list, get, create, update, update_batch, delete, delete_batch
`scout_syncs`	Syncs, sources	list, get, create, update, delete, execute, list_sources
`scout_triggers`	Triggers	list, create, update, delete, execute_slack, execute_telegram, execute_cron
`scout_copilots`	Copilots	list, get, create, update, delete
`scout_logs`	Run logs	list, get_details
`scout_integrations`	Integrations, org	list, list_channels, delete_integration
`scout_drive`	Drive	upload, download
`scout_usage`	Usage	get

Resources

Scout MCP also exposes read-only context resources your agent can inspect at any time:

scout://workflows — list of your workflows
scout://collections — list of your collections
scout://agents — list of your agents

Getting Started

Prerequisites

Node.js 18 or later
A Scout API key — grab one from Settings → API Keys

Install and start the server

Install the package globally with npm:


npm install -g scoutos-mcp

Or run it directly without installing:


npx scoutos-mcp

Set your API key, then start the server:


export SCOUT_API_KEY="your_api_key_here"
scoutos-mcp

The server starts on http://127.0.0.1:9987/mcp by default. You should see output like:


Scout MCP server listening on http://127.0.0.1:9987/mcp

Confirm it is healthy:


curl http://127.0.0.1:9987/health

Customize the port or host


scoutos-mcp --port 3333 --host 127.0.0.1

Run with Docker


docker build -t scoutos-mcp .
docker run -p 9987:9987 -e SCOUT_API_KEY=your_api_key_here scoutos-mcp

Restrict access with a bearer token

If you want to lock down the MCP server so only trusted clients can connect, set a bearer token before starting:


export MCP_SERVER_BEARER_TOKEN="your_secret_token"
scoutos-mcp

Clients must then include this header with every request:


Authorization: Bearer your_secret_token

Environment variables

Variable	Required	Default	Description
`SCOUT_API_KEY`	Yes	—	Your Scout API key
`PORT`	No	`9987`	Server port
`HOST`	No	`127.0.0.1`	Server host
`MCP_SERVER_BEARER_TOKEN`	No	—	Bearer token for client auth

Connect Your Agent

Once the server is running, point your MCP-capable coding agent at:


http://127.0.0.1:9987/mcp

Each agent configures MCP connections differently. Follow the setup guide for yours:

After connecting, your agent will discover all 13 Scout tools automatically — no additional configuration needed.

Example Usage

Here are practical examples of what you can ask your agent to do once Scout MCP is connected.

Explore your workspace


List my Scout workflows and explain what each one does.


Show my collections and summarize which tables look customer-related.


Find the agent named "SDR Assistant" and show its current configuration.

Run and debug workflows


Run workflow <workflow-id> with this sample payload and summarize the output:
{ "company": "Acme Corp", "contact_email": "hello@acme.com" }


Check recent Scout run logs and surface any failures from today.
Show me the error details for any failed runs.

Manage data


Upload this CSV to Scout Drive and then sync it to the customers table.


Create a new collection called "Support Tickets" with a table that has
columns: ticket_id, status, priority, and summary.

Work with triggers


List all my Scout triggers. Which ones are active?
Show me the last time each trigger fired.


Update the Slack trigger on workflow <workflow-id> to only respond
in the #support channel.

Monitor usage


How much of my Scout quota have I used this month?
Break it down by workflow if possible.

Troubleshooting

Issue	What to check
Agent cannot connect	Confirm `scoutos-mcp` is running and the URL matches your configured host and port
`401` or auth errors	Verify `SCOUT_API_KEY` is set in the environment before starting the server
Server starts but tools are missing	Make sure you are on the latest version: `npm update -g scoutos-mcp`
Works in one agent but not another	Confirm each agent points at `http://127.0.0.1:9987/mcp` and reload its MCP config
Health check fails	Run `curl http://127.0.0.1:9987/health` locally; if it fails, restart the server
Bearer token errors	Confirm the value of `MCP_SERVER_BEARER_TOKEN` and the client `Authorization` header match exactly
Port conflict on startup	Another process is using port 9987 — start with `--port 3334` or another free port