Director MCP server
Commit Sep 3, 2026Sits between AI agents and MCP servers to bundle tools and prompts into switchable playbooks accessible through one MCP endpoint.
Also known as fdmtl/director
- Stars
- 482
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 3, 2026
- License
- AGPL-3.0
What is Director MCP?
Director sits between AI agents and MCP servers to bundle tools and prompts into switchable playbooks accessible through one MCP endpoint.
Summary generated from the project's README
About Director MCP server
Organizing and switching between different sets of AI capabilities is what Director enables for developers using MCP-compatible agents. It acts as a middle layer that bundles specific tools, prompts, and configurations into portable units called playbooks. Instead of manually configuring every individual server for every session, you can use a single endpoint to provide an agent with a curated selection of skills tailored to a specific task or environment.
This local-first service integrates with popular clients like Claude Desktop, Claude Code, Cursor, and VSCode through a one-click setup or manual connection. It manages the complexity of MCP by providing centralized JSON logging for observability, tool filtering to preserve context, and unified OAuth for managing authentication across multiple agents. Developers can manage these playbooks through a command-line interface or a web-based studio interface to quickly add, remove, or update server connections.
What you can do with it
- 1Switching agent skillsYou can swap between different sets of tools and prompts for different tasks using playbooks.
- 2Managing agent authenticationConnect to OAuth-protected MCP servers once and use them across all your connected AI agents.
- 3Optimizing agent contextLimit the number of tools available to an agent to ensure it only sees what is necessary for the job.
- 4Monitoring agent actionsUse centralized logging to review the specific actions and tool calls made by your AI client.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefdmtl/director is public and reachablegithub.com/fdmtl/director ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-03github.com/fdmtl/director ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOverview
Director allows you to provide playbooks to AI Agents. A playbook is a set of MCP tools, prompts and configuration, that give agents new skills. You can connect Claude, Cursor and VSCode in 1-click, or integrate manually through a single MCP endpoint.
Playbooks are portable and can easily be switched in and out of context. Director is local-first - setup and client integration takes 30 seconds. In addition, Director provides all of the MCP management functionality that you'd expect: tool filtering, logging, strong isolation, and unified OAuth.
https://github.com/user-attachments/assets/cafc0902-a854-4ee8-ac89-b7535f10c93d
Key Features
- 📚 Playbooks - Maintain sets of tools, prompts and config for different tasks or environments.
- 🚀 1-Click Integration - Switch playbooks with a single click. Currently supports Claude Code, Claude Desktop, Cursor, VSCode
- 🔗 Shareable - Playbooks are accessible through a single MCP endpoint, making them easy to share across agents.
- 🏠 Local-First - Director is local-first, designed to easily run on your own machine or infrastructure.
- 🔑 Unified OAuth - Connect to OAuth MCPs centrally, and use them across all of your agents.
- 🎯 Tool Filtering - Select only the MCP tools that are required for the specific task, preserving context.
- 📊 Observability - Centralized JSON logging, that allows you to understand exactly what your agent is doing.
- 🔌 MCP Compliant - Just works with any MCP server or client. Up to date with the latest MCP spec.
Quickstart
# Install Director
$ curl -LsSf https://director.run/install.sh | sh
# Start the onboarding flow
$ director quickstart
Core Concepts
Playbooks
A playbook is a set of tools, prompts and configuration, used to provide specific capabilities to your agent. Under the hood, playbooks are built on top of the MCP tools & prompts primitives.
The easiest way to author a playbook is via the UI (director studio). But you can also use the CLI. You can have many playbooks, typically one per task or per environment. You can connect to them via a single CLI command or directly over a URL.
Architecture
At a high level, Director is a service that sits between your agents and MCP servers. It's transparent to clients, requiring no additional tokens. It models playbooks, which can be thought of as standalone, portable skills that enhance your AI agent with new capabilities.
Usage
Installation
# Install the director CLI + dependencies (node, npm & uvx) via the 1-liner:
$ curl -LsSf https://director.run/install.sh | sh
# Alternatively, install through npm:
$ npm install -g @director.run/cli
# Start director & open the UI
$ director quickstart
The Studio (Web UI)
The simplest way to interact with director is via the admin interface:
# Open studio in your browser
$ director studio
CLI Reference
Playbooks for your AI agent
USAGE
director <command> [subcommand] [flags]
CORE COMMANDS
quickstart Start the gateway and open the studio in your browser
serve Start the web service
studio Open the UI in your browser
ls List playbooks
get <playbookId> [serverName] Show playbook details
auth <playbookId> <server> Authenticate a server
create <name> Create a new playbook
destroy <playbookId> Delete a playbook
connect <playbookId> [options] Connect a playbook to a MCP client
disconnect <playbookId> [options] Disconnect a playbook from an MCP client
add <playbookId> [options] Add a server to a playbook.
remove <playbookId> <serverName> Remove a server from a playbook
update <playbookId> [serverName] [options] Update playbook attributes
http2stdio <url> Proxy an HTTP connection (sse or streamable) to a stdio stream
env [options] Print environment variables
status Get the status of the director
REGISTRY
registry ls List all available servers in the registry
registry get <entryName> Get detailed information about a registry item
registry readme <entryName> Print the readme for a registry item
MCP
mcp list-tools <playbookId> List tools on a playbook
mcp get-tool <playbookId> <toolName> Get the details of a tool
mcp call-tool <playbookId> <toolName> [options] Call a tool on a playbook
PROMPTS
prompts ls <playbookId> List all prompts for a playbook
prompts add <playbookId> Add a new prompt to a playbook
prompts edit <playbookId> <promptName> Edit an existing prompt
prompts remove <playbookId> <promptName> Remove a prompt from a playbook
prompts get <playbookId> <promptName> Show the details of a specific prompt
FLAGS
-V, --version output the version number
EXAMPLES
$ director create my-playbook # Create a new playbook
$ director add my-playbook --entry fetch # Add a server to a playbook
$ director connect my-playbook --target claude # Connect my-playbook to claude
TypeScript SDK
Programmatic control for advanced use cases:
import { Gateway, GatewayConfig } from "@director.run/sdk";
// Start the gateway
const gateway = await Gateway.start({
config: await GatewayConfig.createMemoryBasedConfig({
defaults: {
server: {
port: 3673,
},
},
}),
baseUrl: "http://localhost:3673",
});
// Add a new playbook
await gateway.playbookStore.create({
name: "test",
servers: [
{
name: "notion",
type: "http",
url: "https://mcp.notion.com/mcp",
},
],
});
Repository Structure
External Apps
apps/gateway- Core gateway and playbook logicapps/cli- The command-line interface, the primary way to interact with Director. Available on npm.apps/sdk- The Typescript SDK, available on npm.apps/docker- The Director docker image, which allows you to run Director (and all MCP servers) securely inside a container. Available on Docker Hub.apps/docs- Project documentation hosted at https://docs.director.runapps/registry- Backend for the registry hosted at https://registry.director.runapps/studio- Director frontend application
Internal Packages
packages/client-configurator- Library for managing MCP client configuration filespackages/mcp- Extensions to MCP SDK that add middleware functionalitypackages/utilities- Shared utilities used across all packages and appspackages/design- Design system: reusable UI components, hooks, and styles for all Director apps
This is a monorepo managed by Turborepo.
Community
If you're using director, have any ideas, or just want to chat about MCP, we'd love to chat:
- 💬 Join our Discord
- 📧 Send us an Email
- 🐛 Report a Bug
- 🐦 Follow us on X / Twitter
Contributing
We welcome contributions! See CONTRIBUTING.mdx for guidelines.
Setting up Development Environment
# Fork and clone
git clone https://github.com/director_run/director
cd director
./scripts/setup-development.sh
bun run test
License
AGPL v3 - See LICENSE for details.
Director MCP questions
What is a playbook in Director?
A playbook is a portable set of MCP tools, prompts and configuration that gives an agent new skills, and you can keep one per task or environment.
Which MCP clients can I connect Director to?
Director supports one-click connection to Claude Code, Claude Desktop, Cursor and VSCode, and can also be integrated manually through a single MCP endpoint.
How do I install Director?
Run the one-line install script, or install the CLI globally through npm, then run the quickstart command.
How does Director handle OAuth for MCP servers?
It provides unified OAuth so you authenticate a server once, centrally, and reuse it across all your agents.
Does Director support tool filtering and logging?
Yes, you can select only the MCP tools needed for a task to preserve context, and get centralized JSON logging of agent activity.