scoutos-mcp

scoutos-mcp is a local MCP (Model Context Protocol) server for the Scout OS API. Install it from npm, set SCOUT_API_KEY, run it on your machine, and connect your coding agent to http://127.0.0.1:9987/mcp.

Alpha Status

This package is currently an alpha release. Expect API coverage, tool actions, packaging details, and client integration guidance to keep evolving before a stable 1.0 release.

Install

npm install -g scoutos-mcp

Or run without a global install:

npx scoutos-mcp

Quick Start

1. Set your Scout API key:

export SCOUT_API_KEY=your_api_key_here

2. Start the local MCP server:

scoutos-mcp

3. Point your MCP client or coding agent at:

http://127.0.0.1:9987/mcp

4. Check health locally:

curl http://127.0.0.1:9987/health

CLI

scoutos-mcp --help

Usage:
  scoutos-mcp [--port <number>] [--host <host>]

Examples:

scoutos-mcp --port 3333
scoutos-mcp --host 127.0.0.1 --port 3333

Environment variables:

• SCOUT_API_KEY: required Scout API key
• PORT: optional port override, defaults to 9987
• HOST: optional host override, defaults to 127.0.0.1
• MCP_SERVER_BEARER_TOKEN: optional bearer token to require on /mcp

Using With Coding Agents

Run scoutos-mcp locally, then configure your MCP-capable tool to use the server URL:

http://127.0.0.1:9987/mcp

If your client supports custom headers and you set MCP_SERVER_BEARER_TOKEN, include:

Authorization: Bearer <your-token>

Overview

This server wraps the Scout OS API and exposes it as a set of MCP tools and resources. It uses the Streamable HTTP transport for remote deployment, allowing any MCP-compatible client to connect.

Architecture

Concern	Choice
Language	TypeScript
MCP SDK	@modelcontextprotocol/sdk
Transport	Streamable HTTP
HTTP Framework	Express
API Base URL	https://api.scoutos.com
Auth	Bearer token (Scout API key)

Tools

The server groups the 79 Scout API endpoints into 13 domain tools with an action parameter, keeping the tool count manageable for LLMs:

Tool	API Coverage	Actions
scout_workflows	/v2/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	Session-based agent endpoints	interact_with_session, interact_sync_with_session, interact_async_with_session
scout_collections	/v2/collections	list, get, create, update, delete
scout_tables	/v2/collections/:id/tables	list, get, create, update, delete, get_schema, sync
scout_documents	Document endpoints	list, get, create, update, update_batch, delete, delete_batch
scout_syncs	/v2/syncs, sources	list, get, create, update, delete, execute, list_sources
scout_triggers	/v2/triggers	list, create, update, delete, execute_slack, execute_telegram, execute_cron
scout_copilots	/v2/copilots	list, get, create, update, delete
scout_logs	/v2/run_logs	list, get_details
scout_integrations	Integrations + org	list, list_channels, delete_integration
scout_drive	/drive	upload, download
scout_usage	/v2/usage	get

Prompts

The server provides built-in MCP prompts that guide agents through common Scout workflows:

Prompt	Purpose
scout_explore	Dynamic account overview — fetches real workflow, agent, and collection names
scout_run_workflow	Step-by-step workflow execution: find, confirm, run, check logs
scout_debug_logs	Troubleshooting guide for failed runs — pulls recent logs, surfaces errors
scout_create_agent	Agent creation walkthrough with data structure guidance
scout_sync_data	Data sync setup: list sources, create sync, execute

The scout_explore prompt is dynamic — it calls the Scout API at prompt time to inject your actual account data into the response.

Progress Notifications

When an MCP client includes a progressToken in its request, the server sends notifications/progress during long-running operations. This lets the agent report status to the user instead of waiting in silence.

Operations that support progress:

Tool	Actions	Steps
scout_workflows	run, run_with_config	Starting → Running → Processing result
scout_agents	interact, interact_sync	Sending → Processing → Reading response
scout_syncs	execute	Starting → Executing → Complete

If the client does not include a progressToken, progress notifications are silently skipped.

Resources

Read-only context resources exposed via MCP:

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

Project Structure

src/
├── index.ts              # MCP server entry, Streamable HTTP transport
├── server.ts             # Tool/resource/prompt definitions
├── api-client.ts         # Scout API client wrapper
├── descriptions.ts       # Rich tool and parameter descriptions
├── progress.ts           # Progress notification helper
├── tools/
│   ├── workflows.ts
│   ├── agents.ts
│   ├── collections.ts
│   ├── tables.ts
│   ├── documents.ts
│   ├── syncs.ts
│   ├── triggers.ts
│   ├── copilots.ts
│   ├── logs.ts
│   ├── integrations.ts
│   ├── drive.ts
│   └── usage.ts
├── prompts/
│   ├── scout-explore.ts
│   ├── scout-run-workflow.ts
│   ├── scout-debug-logs.ts
│   ├── scout-create-agent.ts
│   ├── scout-sync-data.ts
│   └── index.ts
└── resources/
    └── index.ts           # Resource definitions

Development Setup

bun install

Local Development

bun run dev

Testing

vitest run

Build

bun run build

Package Check

npm pack --dry-run

Docker

docker build -t scout-os-mcp-server .
docker run -p 9987:9987 -e SCOUT_API_KEY=your_api_key_here scout-os-mcp-server

Health check:

curl http://localhost:9987/health

Deployment (Scout Live)

The server deploys to Scout Live — a container deployment platform built for AI agents. One API call builds and publishes the app.

Deployment Steps

1. Get a Scout Live API key from scoutos.live/dashboard

2. Deploy with the helper script:

   SCOUT_LIVE_API_KEY=your_live_key ./scripts/deploy.sh mcp-scout
   

3. The server is live at https://mcp-scout.scoutos.live

Environment Configuration

Set the Scout OS API key as a secret on the deployed app:

curl -X POST "https://scoutos.live/api/apps/mcp-scout/env" \
  -H "Authorization: Bearer $SCOUT_LIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "SCOUT_API_KEY", "value": "your_scout_api_key", "secret": true}'

Redeploy

To update the server, re-run the build command with the same subdomain. Scout Live replaces the running app with zero downtime.

Health Check

The server exposes GET /health for Scout Live health checks:

curl https://scoutos.live/api/apps/mcp-scout/health

Delete

curl -X DELETE "https://scoutos.live/api/apps/mcp-scout" \
  -H "Authorization: Bearer $SCOUT_LIVE_API_KEY"

References

• Scout OS API Reference
• MCP Specification
• MCP SDK Documentation