Director: an MCP gateway that groups tools into per-task playbooks
MCP Playbooks for AI agents
At a glance
- What is it?
- Director sits between MCP clients and MCP servers, exposing each named playbook as its own endpoint. The idea is sound and the CLI is complete, but the AGPL licence and the still-thin documentation are the two things to weigh before adopting it.
- Who is it for?
- Adopt Director if you run several MCP servers and want to hand Claude Code, Cursor or VSCode a narrower tool surface per task, and if AGPL-3.0 is acceptable for how you deploy it. Do not adopt it if you need a hosted multi-tenant gateway, or if you cannot run the install script and want a single static binary.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The context-window problem Director is aimed at
Every MCP server you attach to an agent contributes its tool definitions to the model's context. The README frames the consequence directly: Director's tool filtering exists for "selecting only the MCP tools that are required for the specific task, preserving context." That is the problem. An agent wired to a dozen servers carries a dozen tool schemas whether or not the current task needs them, and the schemas compete with the actual work for room in the prompt.
Director's answer is the playbook. A playbook is defined in the README as "a set of tools, prompts and configuration, used to provide specific capabilities to your agent," built on the MCP tools and prompts primitives. Rather than connecting an agent to every server, you connect it to one playbook containing only the servers that task needs, and switch playbooks when the task changes. The intended audience is anyone running more than a couple of MCP servers locally: individual developers using Claude Code or Cursor, and small teams who want the same tool set shared across agents rather than re-declared per client.
What actually sits between the client and the servers
The architecture section is short but unambiguous: "Director is a service that sits between your agents and MCP servers. It's transparent to clients, requiring no additional tokens." So the data flow is client to Director to upstream MCP server, with Director acting as a gateway that presents playbooks as MCP endpoints. The repository topics back this up: mcp-gateway, mcp-host, mcp-middleware, mcp-client and mcp-server all appear.
Because a playbook is exposed as a single MCP endpoint, sharing one across agents is a matter of pointing each client at the same URL rather than copying server configuration into each client. The README also lists unified OAuth and centralised JSON logging as gateway-level features, which only make sense in this middle position: the gateway holds the OAuth session to an upstream server so each agent does not have to, and it sees every tool call passing through, which is what makes the log complete. Tool filtering is applied at the same layer, so what a client sees is the filtered set rather than everything upstream.
One thing the material does not describe is the transport between Director and upstream servers. The CLI includes an http2stdio command that proxies an HTTP connection (SSE or streamable) to a stdio stream, which suggests both transports are handled somewhere in the stack, but the README does not state which side of the gateway each applies to.
Installing Director and creating a first playbook
There are two install paths. The one-liner is `curl -LsSf https://director.run/install.sh | sh`, which the README says installs the CLI plus dependencies: node, npm and uvx. The alternative is `npm install -g @director.run/cli`. After either, `director quickstart` starts the gateway and opens the studio in a browser.
The CLI reference documents the playbook lifecycle. `director create my-playbook` makes a playbook, `director add my-playbook --entry fetch` adds a server by registry entry name, and `director connect my-playbook --target claude` wires it into a client. The README's examples block uses exactly those three commands. Listing and inspection are covered by `director ls` and `director get <playbookId> [serverName]`; removal by `director destroy <playbookId>` and `director remove <playbookId> <serverName>`.
Server discovery goes through the registry subcommands: `director registry ls`, `director registry get <entryName>` and `director registry readme <entryName>`. There are also mcp subcommands for direct invocation (`director mcp list-tools <playbookId>`, `director mcp call-tool <playbookId> <toolName>`) and a prompts group for authoring prompt entries (`director prompts add <playbookId>`, `director prompts edit <playbookId> <promptName>`). If you prefer a UI, `director studio` opens the admin interface, which the README calls the easiest way to author a playbook. For OAuth-protected servers, `director auth <playbookId> <server>` is the command that starts the flow.
For programmatic use, the @director.run/sdk package exposes a Gateway class. The README's example starts one with `Gateway.start`, passing a config built by `GatewayConfig.createMemoryBasedConfig` with `defaults.server.port` set to 3673, and then calls `gateway.playbookStore.create` with a name and a servers array. The snippet is truncated mid-object in the README, so the full server shape is not shown there.
Where Director stops being the right tool
The install script is the first constraint. It pulls in node, npm and uvx as dependencies, so Director is not a self-contained binary. On a machine where you cannot or will not run a remote shell script, the npm route is the only documented alternative, and that still assumes a Node toolchain.
Local-first cuts both ways. The README describes Director as "designed to easily run on your own machine or infrastructure," which is a strength for a single developer and a burden for a team. If the gateway process is not running, the playbook endpoint is not reachable, and every client configured against it loses its tools. There is no documented hosted fallback in the material provided. A `director status` command exists to check the process, but the README does not describe what it reports or whether anything restarts the service for you.
The 1-click integration list is explicit and short: Claude Code, Claude Desktop, Cursor and VSCode. Any other MCP client has to be configured manually against the endpoint URL. That is workable, but it means the convenience argument weakens as soon as your team standardises on a client outside that list.
Finally, the documentation itself is thin in places. The architecture diagram is referenced as an image rather than described in text. The SDK example is cut off. Anyone evaluating Director will spend time in the CLI help output and the studio UI to fill gaps the README leaves.
How this differs from pointing clients straight at servers
The obvious alternative is no gateway at all: configure each MCP client with the servers it needs and let the client manage the connections. Most MCP clients support this, and it avoids a middle process entirely.
The difference is where state lives. With direct configuration, OAuth credentials, server definitions and tool selection are duplicated per client, and changing a tool set means editing each client's config. With Director, that state lives in the playbook on the gateway, and clients only know a URL. The README's claim that playbooks are "portable and can easily be switched in and out of context" depends on this: switching is a gateway-side operation, not a per-client edit.
The trade is a new single point of failure and a new process to keep alive. Direct configuration has no such dependency. There is also a difference in observability: a gateway sees all traffic in one place, which is what makes the centralised JSON log complete, whereas per-client setups scatter that view. If you run one client and two servers, the gateway buys you little. If you run four clients against overlapping server sets, the duplication cost is real and Director removes it.
Licence and what upgrades cost you
Director is AGPL-3.0. That matters more for a gateway than for a library, because AGPL's network clause is triggered by offering the software's functionality to users over a network. If you run Director internally for your own team, the practical exposure is usually low. If you build a product that exposes playbook functionality to your customers, the obligation to provide corresponding source to those users becomes a question for your legal counsel. This is not legal advice; treat it as a reason to read the licence text before you ship anything built on the gateway.
The release history in the supplied material covers only the SDK package: @director.run/sdk at 1.0.2, 1.1.0 and 1.1.1, all published on 2025-10-31. Three SDK releases on a single day suggests rapid iteration on the programmatic surface, which is the part most likely to shift under you if you build against it. The CLI is distributed separately as @director.run/cli on npm. The repository's last push is dated 2026-09-03, so the project is active.
Upgrade cost is concentrated in two places: the SDK API, given that release cadence, and the playbook format if you have authored many of them. The CLI itself is a thin wrapper over the gateway, so CLI upgrades should be cheap. There is no migration guide in the material provided, and no stated support window for older SDK versions.
Editorial conclusion
Adopt Director if you run several MCP servers and want to hand Claude Code, Cursor or VSCode a narrower tool surface per task, and if AGPL-3.0 is acceptable for how you deploy it. Do not adopt it if you need a hosted multi-tenant gateway, or if you cannot run the install script and want a single static binary. Verify first that the registry entry you depend on exists, that the client you use appears in the 1-click target list, and that your agents still work when the local gateway process is stopped.
Community notes