scout_mcp

MCP server and REST API for the Scout Application Capability Intelligence Platform.

Exposes scout.manifest.json to AI coding assistants (Claude Code, Cursor, Windsurf) over the Model Context Protocol and HTTP — so they can answer "what can a teacher do in this app?" without reading a single source file.

The problem it solves

AI coding assistants default to reading source files to understand what an app does. For a 40-screen Flutter app that means scanning ~47,000 tokens of Dart — slow, expensive, and often incomplete.

scout_mcp gives the AI a direct, structured entry point:

Claude: "what can a teacher do?"
→ MCP tool call: get_role_capabilities({ role: "teacher" })
→ Returns 10 capabilities with descriptions, routes, permissions
→ Answer in < 500 tokens, under 2 seconds

Quick start

1. Generate the manifest

dart run build_runner build   # requires scout_builder in your project

2. Start the MCP server

dart run scout_mcp:scout_serve --mcp --transport stdio

3. Wire up Claude Code

// .claude/settings.json
{
  "mcpServers": {
    "scout": {
      "command": "dart",
      "args": ["run", "scout_mcp:scout_serve", "--mcp", "--transport", "stdio"]
    }
  }
}

Restart Claude Code. It can now call Scout MCP tools directly.

MCP tools

list_capabilities

List capabilities, optionally filtered.

{ "role": "teacher", "category": "academic", "search": "attendance" }

All parameters optional. Returns an array of capability objects.

get_role_capabilities

Get all capabilities available to a specific user role.

{ "role": "teacher" }

Use this to answer "what can a role do in this app?"

get_app_context

Get a full summary: all capabilities, categories, route count, and app metadata.

{}

Use this for broad "what does this app do?" questions.

REST API

The server also exposes a REST API at http://localhost:4242 (default port):

GET  /api/v1/capabilities                    All capabilities
GET  /api/v1/capabilities?role=teacher       Filter by role
GET  /api/v1/capabilities?category=academic  Filter by category
GET  /api/v1/capabilities?search=attendance  Keyword search
GET  /api/v1/capabilities/:id                Single capability
GET  /api/v1/roles/:role/capabilities        Role-scoped capabilities
GET  /api/v1/graph                           Full app context
GET  /api/v1/health                          Server health + manifest freshness
GET  /manifest.json                          Raw manifest passthrough

Server modes

# MCP only (stdio) — for Claude Code / Cursor direct integration
dart run scout_mcp:scout_serve --mcp --transport stdio

# REST only — for web dashboards or curl
dart run scout_mcp:scout_serve --rest --port 4242

# Both (default) — MCP stdio + REST in parallel
dart run scout_mcp:scout_serve

# Custom manifest path
dart run scout_mcp:scout_serve --manifest .scout/manifest.json

Token economics

Query Tokens vs full codebase
Full codebase ~47,000 baseline
Full manifest ~14,000 70% less
get_role_capabilities ~1,500 97% less
get_capability (single) ~305 99.4% less

Example interaction

With scout_mcp running as a Claude Code MCP server:

You: What can a teacher do in this app?

Claude: Based on the Scout capability graph, teachers have access to 10 capabilities:

Attendance Management

  • mark_attendance — Record attendance for a class session
  • view_attendance_summary — View attendance summary across all classes

Leave Management

  • approve_leave_request — Approve or reject student leave applications

(... 7 more)

All require authentication. Teachers cannot access admin-only capabilities like manage_fee_structure or view_audit_log.

No source files were read. One MCP round-trip.

Part of Scout

scout_annotations    ← @Capability, @Workflow, @Permission annotations
      ↓
scout_builder        ← build_runner plugin, produces scout.manifest.json
      ↓
scout_cli            ← `scout init`, `scout scan`, `scout validate`
scout_mcp            ← this package

See github.com/runo-ai/scout for the full platform.

License

MIT

Libraries

scout_mcp
Scout MCP server and REST API.