MCP Workflows

MCP Workflows

CCAM's MCP server lets an MCP-capable agent inspect and, when explicitly allowed, operate the dashboard. It exposes structured tools across sessions, agents, transcripts, analytics, alerts, configuration, imports, runs, remote sources, and maintenance.

Choose a transport

Transport	Best for	Boundary
stdio	One local MCP client spawning CCAM	Process/user permissions
HTTP/SSE	Shared or remote MCP clients	Network + MCP auth token
REPL	Human exploration and debugging	Interactive local terminal

Start locally with:

npm run mcp:build
npx ccam mcp stdio

Least-privilege modes

Read-only is the default. Enable writes only for the MCP process that needs them:

MCP_DASHBOARD_ALLOW_MUTATIONS=true npx ccam mcp stdio

Destructive maintenance requires both gates:

MCP_DASHBOARD_ALLOW_MUTATIONS=true \
MCP_DASHBOARD_ALLOW_DESTRUCTIVE=true \
npx ccam mcp stdio

Destructive tools still require operation-specific confirmation tokens. Keep analytical agents read-only and separate them from narrowly scoped administrative clients.

A strong agent workflow

1. List/filter sessions to establish scope.
2. Fetch one session and its agent tree.
3. Read events before requesting transcript pages.
4. State evidence and uncertainty.
5. Propose any mutation with the exact target and expected result.
6. Verify state after an authorized mutation.

This minimizes transcript exposure and prevents broad changes based on a guessed identifier.

Authentication layers

An authenticated dashboard uses MCP_DASHBOARD_API_TOKEN or its file variant. HTTP/SSE transport separately uses MCP_HTTP_AUTH_TOKEN or its file variant; clients send bearer auth or x-mcp-token. These credentials protect different hops and should not be conflated.

Guardrails worth preserving

• Upload and binary-response size limits.
• Canonicalized configuration paths and allowed roots.
• Backup-before-write behavior for supported config artifacts.
• Explicit purge/clear confirmation strings.
• Read-only default on every new MCP process.

For tool names, schemas, and client configuration, use the MCP reference.