outflow-mcp

outflow-mcp

An MCP (Model Context Protocol) server that exposes a live Outflow architecture graph as context for AI coding agents — Claude Code, Claude Desktop, or any other MCP-compatible client. Lets an agent ask "what does this file depend on", "what breaks if I change this", or "did my last batch of edits introduce a circular dependency" against your workspace's real, currently-live graph.

It's a thin client over Outflow's existing /api/v1 REST API and the workspace graph routes — no graph logic is duplicated here.

This package is developed inside the main Outflow monorepo but published from a standalone public mirror: https://github.com/laurells/outflow-mcp — that's the repo MCP registries/crawlers point at, and where npm publish runs from. Changes here get synced there before each release.

Setup

• Create an API key for the workspace you want to expose. In Outflow, go to workspace settings → API Keys → create one. The raw key (ofk_...) is shown once — copy it.
• Find your workspace ID — it's in the workspace URL (.../workspace/<id>/...) or workspace settings.
• Build the server:

  cd packages/mcp-server
  npm install
  npm run build
  

• Add it to your MCP client config. For Claude Code, add to your MCP settings (claude mcp add or the equivalent config file):

  {
    "mcpServers": {
      "outflow": {
        "command": "node",
        "args": ["/absolute/path/to/outflow/packages/mcp-server/dist/index.js"],
        "env": {
          "OUTFLOW_BASE_URL": "https://your-outflow-domain.com",
          "OUTFLOW_API_KEY": "ofk_...",
          "OUTFLOW_WORKSPACE_ID": "your-workspace-id"
        }
      }
    }
  }
  

  For local development, OUTFLOW_BASE_URL defaults to http://localhost:3000 if omitted.

Tools

Tool	Use it to ask
find_node	Is this file tracked? What's its ID?
list_nodes	What's deprecated / low health / a given type?
get_dependencies	What does this file rely on?
get_impact	What breaks if I change this file? (blast radius)
find_path	How are these two files connected?
get_architecture_health	What's the overall health grade and at-risk nodes?
find_architecture_smells	Any circular deps, god nodes, or dead code right now?
get_architecture_graph	Give me the whole graph at a zoom level.
get_last_session_recap	What happened in my last coding session?

All tools that take a path accept a partial match (e.g. "ApiClient" will match src/ApiClient.ts) — you never need to know Outflow's internal file::/method:: ID format. An ambiguous partial match returns an error listing the candidates instead of guessing.

Notes

• This package is standalone — it is never bundled into server/ or web/, and has no build-time dependency on them. It only talks to a running Outflow instance over HTTP using an API key, so it works equally well pointed at localhost or a deployed instance.
• get_dependencies/get_impact and find_architecture_smells/find_path call workspace graph routes that (as of this package's introduction) were extended to accept Authorization: Bearer ofk_... alongside the existing cookie-session auth — see server/src/graph/pathRouter.ts and smellsRouter.ts.