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