Connecting agents (MCP)

NavFlow exposes its read (and authoring) surface to agents over the Model Context Protocol. An MCP client connects, discovers NavFlow’s tools, and calls them. The console’s Agents → Connect tab generates the exact commands below for your instance, with the endpoint and token filled in.

Transports

NavFlow’s MCP server supports two transports.

stdio — the client spawns navflow-mcp as a subprocess; it proxies to the daemon at NAVFLOWD_URL. Use for an agent on the same machine as the daemon, or where the client manages a local process.
streamable-http — the MCP server runs as a network endpoint and the client connects over HTTP. Use for a remote/deployed instance.

navflow-mcp (stdio) is an entry point installed with the package. The HTTP server is started with navflow mcp:


navflow mcp --transport streamable-http --host 0.0.0.0 --port 8788 --navflowd http://localhost:8787
# serves http://<host>:8788/mcp

A bare navflow up does not serve /mcp — that is the daemon only. In the Docker deployment, the compose file runs the MCP server as a separate service and routes /mcp to it, so the endpoint is https://<host>/mcp.

Authentication

If the daemon sets NAVFLOW_AUTH_TOKEN, the MCP surface requires it:

HTTP — the client sends Authorization: Bearer <token>; the server forwards it to the daemon.
stdio — set NAVFLOW_AUTH_TOKEN in navflow-mcp’s environment.

If no auth token is set (e.g. a local instance), no credential is needed.

Clients

Claude Code (plugin)

The NavFlow plugin is the default path for Claude Code — one install wires both directions: the MCP read-back and session capture into the claude_code source.


/plugin marketplace add glassflow/navflow
/plugin install navflow@navflow

The install prompts for the NavFlow URL, an optional auth token (stored in the OS keychain), and a capture toggle. It requires the navflow package on PATH (for navflow-mcp). To connect without capturing sessions, use the CLI tab instead.

Claude Code (CLI)

HTTP (remote/deployed instance):


claude mcp add --transport http navflow https://<host>/mcp \
  --header "Authorization: Bearer <token>"

stdio (same machine as the daemon):


claude mcp add navflow \
  --env NAVFLOWD_URL=http://localhost:8787 \
  -- navflow-mcp

Generic (HTTP)

For Claude Desktop, Cursor, and other clients that take an MCP config object:


{
  "mcpServers": {
    "navflow": {
      "type": "http",
      "url": "https://<host>/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Generic (stdio)

stdio requires the navflow package installed where the agent runs:


{
  "mcpServers": {
    "navflow": {
      "command": "navflow-mcp",
      "env": {
        "NAVFLOWD_URL": "http://localhost:8787",
        "NAVFLOW_AUTH_TOKEN": "<token>"
      }
    }
  }
}

Tools

The MCP server exposes the following tools. In read-only mode (NAVFLOW_READONLY) the write/setup tools are not registered.

tool	kind	description
`read`	read	a correlated, time-ordered timeline across all sources matching a `{label: value}` selector (strict AND) — no view needed
`query`	read	a correlated, time-ordered timeline for an entity through a view; select by `key` or `where`
`catalog_list`	read	list sources, views, and triggers
`catalog_describe`	read	one object’s schema, entities, freshness, lineage, and sample events
`list_sources`	read	sources with their config and live health
`list_connectors`	read	connector types and their fields
`derive`	write	create a view correlating sources for a `key_field`
`remember`	write	write an observation to the agent-memory source
`subscribe`	write	register a webhook to be pushed when a trigger fires
`discover_source`	setup	introspect an upstream and return a proposed source config
`discover_docker`	setup	scan the local Docker environment for sources
`test_source`	setup	dry-run a source config without creating it
`create_source`	setup	create a source (ingestion starts immediately)

A typical agent flow: read any entity on the fly; or catalog_list / catalog_describe to learn what’s there, derive to save a view, query to read it, and remember to write back what it found.

Set up sources with an agent

The setup tools make source configuration conversational — the agent does what you would do in the console form, against the same validation:

Use navflow to ingest the orders table from my Postgres, keyed by tenant_id.

discover_source — introspects the upstream from partial config and returns a proposed source (for Postgres: reads information_schema to pick the cursor and key columns). discover_docker scans the local Docker environment and proposes one source per running container.
test_source — dry-runs the config: fetches sample events without creating anything, so the agent (and you) can check the labels and key before committing.
create_source — creates it; ingestion starts immediately, no restart.

Every connector page shows the agent prompt next to the console and YAML forms. Because all paths normalize to the same stored config, a source an agent creates exports to the same catalog YAML as one you click together.

In-app agent

The console includes an Ask view — the same idea, hosted inside NavFlow. It runs a chat loop on the daemon with the read tools plus derive, using an Anthropic API key you provide in the browser (sent per request, not stored). Use it to explore or debug a source’s data without wiring up an external client. Open it under Ask in the console, or summon it anywhere with ⌘K.