--- title: "MCP Server" description: "Manage projects, configs, targeting rules, and segments from AI coding tools through the Model Context Protocol" canonical_url: "https://docs.configdirector.com/integrations/mcp" --- # MCP Server > Manage projects, configs, targeting rules, and segments from AI coding tools through the Model Context Protocol ## Introduction The ConfigDirector MCP server allows AI coding assistants to read and update your projects, environments, configs, targeting rules, and segments. It runs as a hosted endpoint, so there is nothing to install: ```text https://mcp.configdirector.com ``` It speaks the [Model Context Protocol](https://modelcontextprotocol.io) over Streamable HTTP and authenticates with a ConfigDirector API token. Every update an assistant makes goes through the same validations as the dashboard and the [Admin API](https://docs.configdirector.com/integrations/admin-api). Updates to configs and segments show in the audit log with a source of **MCP**. Code assistant tool calls count as Admin API requests in your organization's usage: one tool call counts as one Admin API request. ## Create an API token 1. In the ConfigDirector dashboard, open **API tokens** and create a token. 2. Choose the permissions the assistant needs. For exploring and answering questions, `Projects: Read`, `Environments: Read`, and `Configs: Read` are enough; add `Contexts: Read` for the assistant to evaluate a config for a context ConfigDirector has stored from SDK evaluations. If you want the assistant to be able to create and update configs and flags, add `Configs: Create`, `Configs: Update settings`, and `Configs: Update targeting rules`; add `Configs: Archive` for it to archive them. For [segments](https://docs.configdirector.com/getting-started/segments), add `Segments: Read` to read them, `Segments: Create` to create them, `Segments: Update` to change them, and `Segments: Delete` to delete them. 3. It's recommended that you set an expiration on the token since it will be stored on your workstation to configure your coding tool of choice. 4. Copy the token, and optionally save it into a password manager. Do not commit the token into source control. 5. The examples below use an environment variable named `CONFIGDIRECTOR_TOKEN`, wherever the tool supports that, to provide the API token. For the project tag catalog, choose `Tags: Read` for listing and lookup and `Tags: Create` for creation. These permissions are independent of config permissions. Existing tokens do not gain tag scopes automatically. The MCP server only exposes the tools that match your token's permissions, so a read-only token produces a read-only assistant. ## What the assistant can do
Tools What they do
list_projects , get_project , create_project , update_project Retrieve projects general information. Create and update projects in your organization.
list_environments , get_environment , create_environment , update_environment Retrieve environments within a project. Create new environments, and update environments.
list_configs , get_config , get_config_activity Retrieve Configs, their targeting rules per environment, and their most recent evaluations. list_configs takes the same search and filters as the configs list in the dashboard.
evaluate_config Evaluate a config for a context in an environment and explain the result: the value served, the rule that served it, and why each rule matched or not. Takes an inline context, a saved context (which also needs Contexts: Read ), or no context at all for an anonymous visitor. Creates no SDK activity.
create_config , update_config_settings Create configs, feature flags, kill switches, or experiments; the role decides the lifetime of every role but config, so only a config needs one. Update their settings, for example, the allowed values in an enum, or update a feature flag to a kill switch and back.
copy_config Copy a config into a new config, in the same project or another project of your organization, with its tags and every environment's targeting rules. Across projects, environments are matched by slug, tags by name, and segments by key: a rule whose segment the destination project doesn't have is left out, and a missing tag is created only with Tags: Create . Each copy reports what it carried over: for each environment, where its rules came from and which rules were left out, and which tags were matched, created, or skipped. A dry run gives that report without creating anything.
archive_config Archive a config. The dashboard can restore it for 30 days.
update_targeting_rules Update the targeting rules of a config in a given environment.
get_targeting_rules_reference Retrieves the targeting rules format, operators, and target types. This is used by the assistant to write valid targeting rules
list_segments , get_segment Retrieve the segments of a project, with their condition groups, environment overrides, and the configs that use them.
create_segment , update_segment , delete_segment Create, update, and delete segments. A segment cannot be deleted while the targeting rules of a config use it.
list_tags , get_tag , find_tag_by_name Browse the shared project tag catalog and resolve a stable ID by name. Requires tags:read .
create_tag Create a shared project tag with a trimmed, case-insensitively unique name of 1–50 characters. Requires tags:create .
`list_configs` lists every config of the project unless the assistant narrows the list down. `search` lists the configs whose key or description contains some text, ignoring case. `role`, `type`, `status` and `lifetime` take one value each: a role (`config`, `flag`, `kill-switch` or `experiment`), a type (`boolean`, `string`, `integer`, `float`, `enum`, `url`, `json` or `timespan`), a lifecycle state (`new`, `in-use`, `settled`, `archive-ready` or `stale`), or `temporary` or `permanent`. `tagIds` lists the configs that have any of the given tags, and `untagged` only the configs without tags. A config is listed only when it matches every filter the assistant sends, and filtering needs only `Configs: Read`. For example, asking for the stale feature flags of a project sends `role: flag` and `status: stale`. Tag names preserve display casing and allow spaces and punctuation. Name lookup ignores differences in casing and leading or trailing whitespace. Tags do not affect evaluation or appear in SDK payloads. A tag that was deleted matches no config, so asking only for deleted tags lists no configs rather than all of them. Things you can ask once connected: - "List the flags in the checkout project." - "Which flags in the checkout project are settled and ready to remove from the code?" - "Create a kill switch called payments-v2 in the checkout project, off in all environments." - "new-checkout is staying for good. Make it a kill switch." - "In production, roll new-search out to 10 percent of users, and to everyone whose email ends in @example.com." - "Create a beta testers segment for everyone whose email ends in @example.com, and turn new-search on for it in staging." - "Which configs in production have not been evaluated in the last week?" - "What does user 123 get for new-checkout in production, and why?" The assistant sees a short guide to ConfigDirector's vocabulary when it connects (roles, lifetimes, types, how targeting rules work, and segments), so you can talk about configs, feature flags, rollouts, and segments in plain terms. ## Claude Code Add the server for yourself in the current project (the default), for yourself in every project with `--scope user`, or for the whole team with `--scope project`, which writes `.mcp.json` in the project root: ```bash claude mcp add --transport http configdirector https://mcp.configdirector.com \ --header 'Authorization: Bearer ${CONFIGDIRECTOR_TOKEN}' ``` The single quotes keep your shell from putting the token itself in the configuration: Claude Code reads `CONFIGDIRECTOR_TOKEN` each time it starts, so a token you replace takes effect on the next start, and `--scope project` commits only the variable's name. Or write `.mcp.json` by hand. Claude Code expands environment variables in the `url` and `headers` fields, so the token stays out of the repository: ```json [.mcp.json] { "mcpServers": { "configdirector": { "type": "http", "url": "https://mcp.configdirector.com", "headers": { "Authorization": "Bearer ${CONFIGDIRECTOR_TOKEN}" } } } } ``` Type `/mcp` inside Claude Code to check: the server should show as connected with its tools listed. From a terminal, `claude mcp list` shows the same. ## Cursor Create `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project. Cursor expands `${env:NAME}` in this file: ```json [.cursor/mcp.json] { "mcpServers": { "configdirector": { "url": "https://mcp.configdirector.com", "headers": { "Authorization": "Bearer ${env:CONFIGDIRECTOR_TOKEN}" } } } } ``` Open Cursor's MCP settings to confirm the server is enabled and its tools are listed. The variable has to be set in the environment Cursor was launched from. ## VS Code with GitHub Copilot Create `.vscode/mcp.json`. The `inputs` entry makes VS Code prompt for the token once and store it securely, so nothing sensitive goes in the file: ```json [.vscode/mcp.json] { "inputs": [ { "type": "promptString", "id": "configdirector-token", "description": "ConfigDirector API token", "password": true } ], "servers": { "configdirector": { "type": "http", "url": "https://mcp.configdirector.com", "headers": { "Authorization": "Bearer ${input:configdirector-token}" } } } } ``` Run **MCP: List Servers** from the command palette to start the server and see its status. The tools appear in the Copilot chat tools picker in agent mode. ## Windsurf Open the MCP settings from the Cascade panel, or edit `~/.codeium/windsurf/mcp_config.json`. Windsurf expands `${env:NAME}` in this file: ```json [mcp_config.json] { "mcpServers": { "configdirector": { "serverUrl": "https://mcp.configdirector.com", "headers": { "Authorization": "Bearer ${env:CONFIGDIRECTOR_TOKEN}" } } } } ``` ## OpenAI Codex CLI Add to `~/.codex/config.toml`. Codex reads the token from the named environment variable at startup: ```toml [~/.codex/config.toml] [mcp_servers.configdirector] url = "https://mcp.configdirector.com" bearer_token_env_var = "CONFIGDIRECTOR_TOKEN" ``` Run `codex mcp list` to confirm. ## Gemini CLI Add to `~/.gemini/settings.json`, or to the project's `.gemini/settings.json`. Gemini CLI expands `$NAME` in string values: ```json [settings.json] { "mcpServers": { "configdirector": { "httpUrl": "https://mcp.configdirector.com", "headers": { "Authorization": "Bearer $CONFIGDIRECTOR_TOKEN" } } } } ``` Or add it from the command line: ```bash gemini mcp add --transport http configdirector https://mcp.configdirector.com \ --header "Authorization: Bearer ${CONFIGDIRECTOR_TOKEN}" ``` Type `/mcp` in Gemini CLI to see the server and its tools. ## Claude Desktop and other tools without header support Claude Desktop's custom connectors expect OAuth sign-in, which the ConfigDirector server does not offer yet. Until then, bridge it with [mcp-remote](https://github.com/geelen/mcp-remote), which runs locally and forwards to the hosted server with your token. Edit `claude_desktop_config.json` (**Settings → Developer → Edit Config**): ```json [claude_desktop_config.json] { "mcpServers": { "configdirector": { "command": "npx", "args": ["mcp-remote", "https://mcp.configdirector.com", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer " } } } } ``` The header value goes through an environment variable because some desktop clients split arguments on spaces. The same bridge works for any client that can only launch a local command. ## More than one organization An API token belongs to one organization, so working for two organizations means one token each. Give each repository its own configuration that reads a variable named for the organization, such as `CONFIGDIRECTOR_TOKEN_ACME` and `CONFIGDIRECTOR_TOKEN_GLOBEX`, and set both variables in your shell. For Claude Code, add the server in each repository with the default scope, which is local to that repository and to you: ```bash cd ~/code/acme-storefront claude mcp add --transport http configdirector https://mcp.configdirector.com \ --header 'Authorization: Bearer ${CONFIGDIRECTOR_TOKEN_ACME}' cd ~/code/globex-portal claude mcp add --transport http configdirector https://mcp.configdirector.com \ --header 'Authorization: Bearer ${CONFIGDIRECTOR_TOKEN_GLOBEX}' ``` The same works for Cursor, VS Code and Gemini CLI, whose configuration file lives in the repository. Do not set `CONFIGDIRECTOR_TOKEN` for every terminal: the [CLI](https://docs.configdirector.com/integrations/cli#more-than-one-organization) uses that variable ahead of its own sign-ins, so a command in the other organization's repository would send the wrong token and stop. Windsurf, Codex and Claude Desktop read one configuration for every repository, so the variable it names has to hold the right organization's token where the tool starts, for example from a loader such as direnv that sets it per directory. Otherwise, let that tool work for one organization, and reach the other through the CLI, which keeps one sign-in per organization. ## Limits and billing - Each tool call counts as one Admin API request against the monthly [free allowance](https://docs.configdirector.com/getting-started/pricing-and-billing#the-free-allowance). Connecting and listing tools does not. - An organization can make up to 60 tool calls per minute across all of its tokens. If that limit is exceeded, the assistant receives a message asking it to wait until the next minute. - Any update the assistant makes is validated like any other: type constraints, JSON Schema, and the hourly [JSON Schema budgets](https://docs.configdirector.com/getting-started/json-schema-validation#hourly-budgets-on-free) on Free all apply, and the assistant receives the same messages you would see in the dashboard. - Every update appears in the audit log of the config or segment with the source **MCP** and the token owner's name. ## Security notes - Prefer environment variables or your editor's secret storage over tokens written into config files. Project-level files such as `.mcp.json` and `.cursor/mcp.json` are usually committed, do not add an API token to them. - Give each tool its own token with the smallest permission set needed. Revoke the token from the API tokens page when you are no longer using the tool. - You can rename a token or change its permissions from the API tokens page without replacing the token. Assistants see newly allowed tools after they reconnect. - The MCP server never returns SDK keys or API tokens. ## Sitemap See the full [sitemap](https://docs.configdirector.com/sitemap.md) for all pages.