> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scoutos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Scout MCP Server: Connect Your Coding Agent to Scout
> Run the Scout MCP server to give coding agents like Cursor and Claude Code direct access to Scout workflows, agents, databases, and Drive.
Scout MCP is a local [Model Context Protocol](https://modelcontextprotocol.io/specification/latest) server that gives your coding agent direct access to the Scout OS API. Run it once and your agent can list workflows, manage databases, trigger automations, upload files, and interact with agents — all from inside its context window, without writing integration code or copy-pasting credentials manually.
## 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.
With Scout MCP running, your agent can:
* Query and manage your Scout workflows, agents, and databases
* 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.
## What Scout MCP Exposes
Scout MCP wraps the [Scout OS API](https://ref.scoutos.com) and exposes it as **13 domain tools** covering **79 API endpoints**. Each tool accepts an `action` parameter (`list`, `get`, `create`, `update`, `delete`) so your agent can operate on any Scout resource through a consistent interface.
### Tool Coverage
| 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_databases` | Databases | 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 storage | upload, download |
| `scout_usage` | Usage metrics | get |
### Resources
Scout MCP also exposes three read-only context resources your agent can inspect at any time without making tool calls:
| Resource URI | What it contains |
| ------------------- | ------------------------------------------ |
| `scout://workflows` | List of all workflows in your organization |
| `scout://databases` | List of all databases in your organization |
| `scout://agents` | List of all agents in your organization |
## Getting Started
### Prerequisites
Before starting the Scout MCP server, make sure you have:
* **Node.js 18 or later** installed
* A **Scout API key** — grab one from [Settings → API Keys](/settings/api-keys)
### Install and Start the Server
Install Scout MCP globally with npm:
```bash theme={null}
npm install -g scoutos-mcp
```
Or run it directly without a global install:
```bash theme={null}
npx scoutos-mcp
```
Export your Scout API key as an environment variable:
```bash theme={null}
export SCOUT_API_KEY="your_api_key_here"
```
Launch the Scout MCP server:
```bash theme={null}
scoutos-mcp
```
You should see:
```text theme={null}
Scout MCP server listening on http://127.0.0.1:9987/mcp
```
Confirm the server is running and accessible:
```bash theme={null}
curl http://127.0.0.1:9987/health
```
Point your MCP-capable coding agent at:
```text theme={null}
http://127.0.0.1:9987/mcp
```
Your agent will discover all 13 Scout tools automatically — no additional configuration needed.
### Connect Your Agent
Each coding agent configures MCP connections differently. Follow the setup guide for yours:
Add Scout MCP as an MCP server in your Claude Code settings.
Configure Scout MCP in Cursor's MCP settings panel.
Connect Scout MCP to Codex via the MCP integration settings.
Add Scout MCP as an MCP server in your OpenCode configuration.
## Configuration
### Customize Port and Host
Start the server on a different port or host if the defaults conflict with another process:
```bash theme={null}
scoutos-mcp --port 3333 --host 127.0.0.1
```
### Run with Docker
If you prefer to run Scout MCP in a container:
```bash theme={null}
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
Lock down the MCP server so only trusted clients can connect by setting a bearer token before starting:
```bash theme={null}
export MCP_SERVER_BEARER_TOKEN="your_secret_token"
scoutos-mcp
```
Clients must then include this header with every request:
```text theme={null}
Authorization: Bearer your_secret_token
```
### Environment Variables
Your Scout API key. Used to authenticate all requests Scout MCP makes to the Scout OS API.
The port the MCP server listens on. Defaults to `9987`.
The host address the MCP server binds to. Defaults to `127.0.0.1`.
When set, the MCP server requires clients to present this value as a Bearer token. Leave unset for local development with no client auth.
## Example Usage
Once Scout MCP is connected, here are practical things you can ask your agent to do.
### Explore your workspace
```text theme={null}
List my Scout workflows and explain what each one does.
```
```text theme={null}
Show my databases and summarize which tables look customer-related.
```
```text theme={null}
Find the agent named "SDR Assistant" and show its current configuration.
```
### Run and debug workflows
```text theme={null}
Run workflow wf_abc123 with this sample payload and summarize the output:
{ "company": "Acme Corp", "contact_email": "hello@acme.com" }
```
```text theme={null}
Check recent Scout run logs and surface any failures from today.
Show me the error details for any failed runs.
```
### Manage data
```text theme={null}
Upload this CSV to Scout Drive and then sync it to the customers table.
```
```text theme={null}
Create a new database called "Support Tickets" with a table that has
columns: ticket_id, status, priority, and summary.
```
### Work with triggers
```text theme={null}
List all my Scout triggers. Which ones are active?
Show me the last time each trigger fired.
```
```text theme={null}
Update the Slack trigger on workflow wf_abc123 to only respond
in the #support channel.
```
### Monitor usage
```text theme={null}
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. Restart the server after setting it. |
| 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, stop and 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. |
After updating `scoutos-mcp` with `npm update -g scoutos-mcp`, restart the server for changes to take effect. Your agent will re-discover the updated tool list automatically.
## References
Source code, changelogs, and open issues for the Scout MCP server.
Full reference for all 79 Scout API endpoints exposed through Scout MCP.
The open standard Scout MCP implements for agent-to-service communication.