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

1. Start the local MCP server:

scoutos-mcp

1. Point your MCP client or coding agent at:

http://127.0.0.1:9987/mcp

1. 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

Tools

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

Prompts

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

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:

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