Director: MCP Playbooks for AI Agents, Reviewed

The problem Director solves for MCP-heavy agent setups

Once you have more than a handful of MCP servers, every client you use needs its own configuration file, its own OAuth dance and its own copy of the same server list. Adding a tool for one task means it is now present in every conversation, consuming context whether or not the task needs it. Director's answer is the playbook: a named set of MCP tools, prompts and configuration that you switch in and out as a unit. The README describes a playbook as "a set of MCP tools, prompts and configuration, that give agents new skills", and the CLI exposes them as first-class objects with create, destroy, add, remove and update commands. The audience is engineers who already use MCP clients and want task-scoped capability sets rather than one flat global tool list. It is not aimed at someone who has never configured an MCP server; the vocabulary assumes you know what a tool, a prompt and a transport are.

How the gateway sits between agents and MCP servers

Director runs as a service between your agents and your MCP servers. The README states it is "transparent to clients, requiring no additional tokens", and that playbooks are reachable through a single MCP endpoint, which is what makes them shareable across agents. Each playbook is a separate endpoint, so Claude Code can point at one playbook while Cursor points at another, and switching is a client-side change rather than a server-side reconfiguration. Around that core the project lists tool filtering, centralized JSON logging, isolation between playbooks and unified OAuth, so an OAuth-backed server is authenticated once and reused by every agent connected to that playbook. The TypeScript SDK exposes the same model programmatically: a Gateway is started with a GatewayConfig, and playbooks are created through gateway.playbookStore. The repository is a Turborepo monorepo with apps/ and packages/ directories, and package.json shows a serve script that runs the gateway server, a studio script for the UI, and a separate registry app. A docker-compose.yml in the repository root starts a Postgres 17 container on port 5432, which suggests a database-backed deployment path alongside the local-first one.

Installing Director and connecting a first playbook

The README gives two installation routes. The one-liner installs the CLI plus its dependencies (node, npm and uvx). The npm route installs only the CLI package, so you need node and npm present already.

curl -LsSf https://director.run/install.sh | sh

npm install -g @director.run/cli

After installing, the documented first step is the onboarding flow, which starts the gateway and opens the studio in your browser.

director quickstart

The CLI reference lists the commands you will use next. This sequence creates a playbook, adds a server from the registry, and connects it to Claude.

director create my-playbook
director add my-playbook --entry fetch
director connect my-playbook --target claude

The README shows those three lines verbatim as examples, so the flag names are --entry and --target. To confirm what was registered, director ls lists playbooks and director mcp list-tools <playbookId> lists the tools on one. If you would rather work in a browser, director studio opens the admin interface, which the README calls "the easiest way to author a playbook".

Where Director is the wrong tool

The most concrete limitation is transport. The CLI reference includes an http2stdio command that proxies an HTTP connection (sse or streamable) to a stdio stream, which tells you Director speaks to servers over HTTP and offers a bridge for stdio clients. If your agent only speaks stdio and you do not want a long-running local service in the path, the gateway adds a process you must keep running. The second limitation is the deployment model. The README calls Director local-first and describes running it on your own machine or infrastructure; the docker-compose.yml in the repository is explicitly labelled a development environment, and its comment points at a separate director-docker repository for the production image. Nothing in the README describes multi-tenant hosting, per-user quotas or horizontal scaling, so treating it as a shared internal gateway for a whole organisation is an assumption the documentation does not support. Third, the README does not document rollback or version pinning for the CLI, and the install script is fetched from a URL and piped to sh, which means you are trusting whatever that endpoint serves at install time. If your environment requires pinned, auditable installs, use the npm package and pin the version yourself.

How Director differs from running mcp-proxy or a plain config file

The common alternative is a per-client configuration file plus a small stdio-to-HTTP proxy such as mcp-proxy or the http2stdio subcommand Director already ships. That approach keeps one flat list of servers per client. It has no concept of a task-scoped group, so enabling a server for one job enables it everywhere, and each client repeats the OAuth flow for the same server. Director's difference is that the grouping is the primary object: a playbook is created, populated, connected and disconnected as a unit, and the same playbook endpoint can be handed to several agents. The trade-off is a stateful service with a store behind it. A config file is inert and diffable; a playbook lives in Director's state, and the CLI reference shows auth, update and env commands that imply credentials and environment variables are managed there too. If your setup is one agent and two servers, the config file wins on simplicity. Director starts paying off when the number of servers or the number of clients grows, or when the same OAuth-protected server needs to serve several agents.

Licence and the ongoing cost of running Director

The repository licence is AGPL-3.0, and package.json repeats that identifier. For internal use this is usually unremarkable, but AGPL-3.0 carries network-copyleft obligations: if you modify Director and expose it to users over a network, the licence terms apply to that modified service. If you plan to embed it in a closed product, read LICENSE in full and get your own legal advice; nothing here substitutes for that. On maintenance, the last push to the repository was on 2026-09-03, so the project is being worked on, but the most recent release listed is @director.run/[email protected] from 2025-10-31. That gap is worth noting: the SDK version you install through npm may lag the code on main. The repository uses Changesets (.changeset/ is a top-level entry, and package.json has changeset and version-packages scripts), so version bumps are deliberate rather than continuous. Upgrading means watching the CLI and SDK packages separately, and the README does not document a migration path between playbook schema versions.

Working with the TypeScript SDK instead of the CLI

For programmatic control the README points at @director.run/sdk. The example starts a gateway with a memory-based config and a server port of 3673, then creates a playbook through the store.

import { Gateway, GatewayConfig } from "@director.run/sdk";

const gateway = await Gateway.start({
  config: await GatewayConfig.createMemoryBasedConfig({
    defaults: {
      server: {
        port: 3673,
      },
    },
  }),
  baseUrl: "http://localhost:3673",
});

The README's snippet is truncated at the playbook creation call, so the full shape of a server entry is not shown there. The CLI reference is the safer guide for what a server entry needs: director add takes a playbook id and an --entry flag naming a registry item, and director registry ls lists what is available. If you build on the SDK, treat the CLI's add and get commands as the reference for the data model, and check the SDK's own types for the fields the README cuts off.

Editorial conclusion

Adopt Director if you already run several MCP servers and want per-task tool sets that you can switch between Claude Code, Claude Desktop, Cursor and VSCode without editing each client's config by hand. Skip it if you need a stdio-only setup, a permissive licence for a closed product, or a hosted multi-tenant gateway, since the README describes a local-first single-machine service and the licence is AGPL-3.0. Before committing, run director status and director ls on your own machine to confirm the gateway starts and your existing servers register, then read LICENSE and SECURITY.md in the repository rather than relying on the badge.

Frequently asked questions

Official sources

1. fdmtl/director on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases