DevCycle MCP Server Documentation
Overview
The DevCycle MCP (Model Context Protocol) Server enables AI coding assistants like Cursor and Claude to interact directly with DevCycle's feature flag management system. This integration allows developers to manage feature flags, variables, and targeting rules without leaving their coding environment.
DevCycle provides two MCP implementations:
- Local MCP Server (
dvc-mcp
): Runs locally using CLI authentication or API keys - Remote MCP Server (
https://mcp.devcycle.com
): Hosted Cloudflare Worker with OAuth authentication
Both implementations share the same underlying tools, schemas, and utilities, ensuring consistent functionality regardless of which option you choose.
Table of Contents
Installation & Setup
Local MCP Server
Prerequisites
- Node.js 18+ installed
- DevCycle CLI installed globally:
npm install -g @devcycle/cli
- DevCycle account with API credentials or SSO authentication
Local Configuration
For Cursor (.cursor/mcp_settings.json
):
{
"mcpServers": {
"devcycle": {
"command": "dvc-mcp"
}
}
}
For Claude Desktop:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"devcycle": {
"command": "dvc-mcp"
}
}
}
Remote MCP Server (Cloudflare Worker)
The remote MCP server provides OAuth-based authentication and requires no local installation.
Remote Configuration
For Cursor (.cursor/mcp_settings.json
):
{
"mcpServers": {
"devcycle": {
"url": "https://mcp.devcycle.com/mcp"
}
}
}
For Claude Desktop:
{
"mcpServers": {
"devcycle": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.devcycle.com/mcp"
]
}
}
}
For more details about the remote MCP implementation, see the MCP Worker README.
Authentication
Local MCP Server Authentication
The local MCP server supports two authentication methods:
1. Environment Variables (Recommended for CI/CD)
export DEVCYCLE_CLIENT_ID="your-client-id"
export DEVCYCLE_CLIENT_SECRET="your-client-secret"
export DEVCYCLE_PROJECT_KEY="your-project-key"
2. CLI Authentication (Recommended for local development)
# Authenticate via SSO
dvc login sso
# Select your project
dvc projects select
Remote MCP Server Authentication
The remote MCP server uses OAuth 2.0 authentication:
- Users authenticate through DevCycle's Auth0 tenant
- No API keys or local credentials needed
- Project selection is handled through the
select_project
tool
Available Tools
All tools listed below are available in both the local and remote MCP implementations. They share the same schemas, validation, and behavior.
Warning Symbols
- ⚠️ - This tool can affect production environments. The AI will confirm with you before executing.
- ⚠️⚠️ - This tool performs destructive operations (deletions). The AI will require explicit confirmation before executing.
Feature Management
list_features
List all features in the current project with optional search and pagination.
Parameters:
search
(optional): Search query to filter features (minimum 3 characters)page
(optional): Page number (default: 1)perPage
(optional): Items per page (default: 100, max: 1000)sortBy
(optional): Sort field (createdAt
,updatedAt
,name
,key
,createdBy
,propertyKey
)sortOrder
(optional): Sort order (asc
,desc
)staleness
(optional): Filter by staleness (all
,unused
,released
,unmodified
,notStale
)createdBy
(optional): Filter by creator user IDtype
(optional): Feature type (release
,experiment
,permission
,ops
)status
(optional): Feature status (active
,complete
,archived
)
create_feature
⚠️
Create a new feature flag. The AI assistant will guide you through a complete feature setup:
- Create a variable and associate it with the feature (defaults to a boolean variable with the same key)
- Create variations for the feature (defaults to "on" and "off" variations)
- Set and enable initial targeting for at least the development environment (defaults to all users with "on" variation)
Parameters:
key
: Unique feature key (pattern:^[a-z0-9-_.]+$
)name
: Human-readable name (max 100 chars)description
(optional): Feature description (max 1000 chars)type
(optional): Feature type (release
,experiment
,permission
,ops
)tags
(optional): Array of tags for organizationvariations
(optional): Array of variations with key, name, and variablesconfigurations
(optional): Environment-specific configurationssdkVisibility
(optional): SDK visibility settingsvariables
(optional): Array of variables to create or reassociate with this featurecontrolVariation
(optional): The key of the variation that is used as the control for Metricssettings
(optional): Feature-level settings configurationinteractive
(optional): MCP-only hint to prompt for missing fields
update_feature
⚠️
Update an existing feature flag.
Parameters:
key
: Feature key to updatename
(optional): New namedescription
(optional): New descriptiontype
(optional): New typetags
(optional): New tagsvariations
(optional): Updated variationsvariables
(optional): Updated array of variables for this featuresettings
(optional): Updated feature-level settings configurationsdkVisibility
(optional): Updated SDK visibility settingscontrolVariation
(optional): Updated control variation key for Metrics
update_feature_status
⚠️
Update the status of a feature flag.
Parameters:
key
: Feature keystatus
: New status (active
,complete
,archived
)staticVariation
(optional): Variation to serve if status iscomplete
delete_feature
⚠️⚠️
Delete a feature flag from ALL environments.
Parameters:
key
: Feature key to delete
cleanup_feature
Fetch the DevCycle Feature Cleanup prompt and return its markdown content to guide safe cleanup of a completed feature and its variables in codebases.
Parameters:
featureKey
: The feature key you plan to clean up (used for context in the prompt)
get_feature_audit_log_history
Get feature flag audit log history from DevCycle. Returns audit log entities matching the DevCycle API schema with date, a0_user, and changes fields.
Parameters:
feature_key
: Feature keypage
(optional): Page number for pagination (default: 1)perPage
(optional): Number of items per page (default: 100, max: 1000)sortBy
(optional): Field to sort by (createdAt
,updatedAt
,action
,user
) (default:createdAt
)sortOrder
(optional): Sort order (asc
,desc
) (default:desc
)startDate
(optional): Start date for filtering (ISO 8601 format)endDate
(optional): End date for filtering (ISO 8601 format)environment
(optional): Environment key to filter byuser
(optional): User ID to filter byaction
(optional): Action type to filter by
Variable Management
list_variables
List all variables in the current project.
Parameters:
search
(optional): Search querypage
(optional): Page numberperPage
(optional): Items per pagesortBy
(optional): Sort field (createdAt
,updatedAt
,name
,key
,createdBy
,propertyKey
)sortOrder
(optional): Sort order (asc
,desc
)feature
(optional): Filter by feature keytype
(optional): Variable type (String
,Boolean
,Number
,JSON
)status
(optional): Variable status (active
,archived
)
create_variable
⚠️
Create a new variable.
Parameters:
key
: Unique variable key (pattern:^[a-z0-9-_.]+$
)type
: Variable type (String
,Boolean
,Number
,JSON
)name
(optional): Variable namedescription
(optional): Variable descriptiondefaultValue
(optional): Default value_feature
(optional): Associated feature keyvalidationSchema
(optional): Validation rules
update_variable
⚠️
Update an existing variable.
Parameters:
key
: Variable key to updatename
(optional): New namedescription
(optional): New descriptiontype
(optional): New typevalidationSchema
(optional): New validation rules
delete_variable
⚠️⚠️
Delete a variable from ALL environments.
Parameters:
key
: Variable key to delete
Project Management
get_current_project
Get details of the currently selected project.
Returns the project defined by your current MCP context. If no project is selected:
- Remote Worker: use the
select_project
tool - Local MCP: configure a project via
dvc projects select
or setDEVCYCLE_PROJECT_KEY
Parameters: None
select_project
Select a project to use for subsequent MCP operations.
- Local MCP: updates your local DevCycle configuration at
~/.config/devcycle/user.yml
- Remote MCP: stores the selection in the worker state for your session
Parameters:
projectKey
(optional): The project key to select. If not provided, lists available projects
SDK Installation
install_devcycle_sdk
Fetch DevCycle SDK installation instructions for your platform/language and follow the steps to install. Returns the corresponding guide markdown.
Parameters:
guide
: Install guide identifier
Supported guide identifiers:
android
,android-openfeature
,angular
,dotnet
,dotnet-openfeature
,flutter
,go
,go-openfeature
,ios
,ios-openfeature
,java
,java-openfeature
,javascript
,javascript-openfeature
,nestjs
,nestjs-openfeature
,nextjs
,nodejs
,nodejs-openfeature
,php
,php-openfeature
,python
,python-openfeature
,react
,react-native
,react-openfeature
,roku
,ruby
,ruby-openfeature
Self-Targeting & Overrides
get_self_targeting_identity
Get current DevCycle identity for self-targeting.
Parameters: None
Returns your current DevCycle identity for the selected project, along with a dashboard link to profile overrides.
update_self_targeting_identity
Update DevCycle identity for testing.
Parameters:
dvc_user_id
: DevCycle User ID (use empty string to clear)
Updates your identity for self-targeting and testing. Use null
or empty string to clear.
list_self_targeting_overrides
List all active overrides for the current project.
Parameters: None
Lists all active overrides for the current project for your identity.
set_self_targeting_override
⚠️
Set an override to test a specific variation.
Parameters:
feature_key
: Feature keyenvironment_key
: Environment keyvariation_key
: Variation to serve
Important: Confirm with the user before setting overrides in production environments.
clear_feature_self_targeting_overrides
⚠️
Clear overrides for a specific feature/environment.
Parameters:
feature_key
: Feature keyenvironment_key
: Environment key
Important: Confirm with the user before clearing overrides in production environments.
Results & Analytics
get_feature_total_evaluations
Get total variable evaluations per time period for a specific feature.
Parameters:
featureKey
: Feature keystartDate
(optional): Start date as Unix timestamp (milliseconds since epoch)endDate
(optional): End date as Unix timestamp (milliseconds since epoch)platform
(optional): Platform filter for evaluation resultsvariable
(optional): Variable key filter for evaluation resultsenvironment
(optional): Environment key to filter resultsperiod
(optional): Time aggregation period (day
,hour
,month
)sdkType
(optional): Filter by SDK type (client
,server
,mobile
,api
)
get_project_total_evaluations
Get total variable evaluations per time period for the entire project.
Parameters:
startDate
(optional): Start date as Unix timestamp (milliseconds since epoch)endDate
(optional): End date as Unix timestamp (milliseconds since epoch)platform
(optional): Platform filter for evaluation resultsvariable
(optional): Variable key filter for evaluation resultsenvironment
(optional): Environment key to filter resultsperiod
(optional): Time aggregation period (day
,hour
,month
)sdkType
(optional): Filter by SDK type (client
,server
,mobile
,api
)
Error Handling
The MCP server returns structured error responses:
{
"errorType": "AUTHENTICATION_ERROR",
"errorMessage": "401 Unauthorized",
"toolName": "list_features",
"suggestions": [
"Re-authenticate with DevCycle (run \"dvc login sso\" for CLI for local MCP or re-login through OAuth for remote MCP)",
"Verify your API credentials are correct",
"Check if your token has expired"
],
"timestamp": "2025-07-01T00:00:00.000Z"
}
Fields:
- errorType: One of
AUTHENTICATION_ERROR
,PERMISSION_ERROR
,RESOURCE_NOT_FOUND
,VALIDATION_ERROR
,SCHEMA_VALIDATION_ERROR
,RATE_LIMIT_ERROR
,NETWORK_ERROR
,PROJECT_ERROR
,UNKNOWN_ERROR
. - errorMessage: Human-readable error description.
- toolName: The MCP tool that produced the error.
- suggestions: Remediation steps tailored to the error type.
- timestamp: ISO 8601 timestamp when the error was generated.
Common error scenarios:
- Authentication failures: Check credentials and project configuration
- API rate limits: Implement retry logic in your automation
- Validation errors: Ensure parameters meet requirements (patterns, lengths, etc.)
- Permission errors: Verify your API key has necessary permissions
Usage Examples
Creating a Feature Flag
Create a feature flag for the new checkout flow with variations for A/B testing
The AI assistant will use:
create_feature
to create the feature, providing variables, variations, and initial environment configurations in one step
Viewing Analytics
Show me the evaluation metrics for the checkout_flow feature over the last week
The AI assistant will use:
get_feature_total_evaluations
with appropriate date range- Display the evaluation data grouped by time period
Managing Overrides for Testing
Set up my identity to test the premium user experience
The AI assistant will use:
update_self_targeting_identity
to set your user IDset_self_targeting_override
to force specific variations
Analyzing Feature Usage
Show me the recent changes to the checkout_flow feature
The AI assistant will use:
get_feature_audit_log_history
to retrieve change history
Best Practices
1. Production Safety
Tools marked with ⚠️ can affect production environments. The AI will confirm before:
- Creating or updating features/variables
- Enabling/disabling targeting
- Setting overrides in production
Tools marked with ⚠️⚠️ are destructive and require extra confirmation.
2. Naming Conventions
- Feature keys:
lowercase_with_underscores
orkebab-case
- Variable keys: Follow the same pattern as features
- Must match pattern:
^[a-z0-9-_.]+$
- Maximum 100 characters
3. Environment Management
- Use consistent environment keys across projects
- Common pattern:
development
,staging
,production
- Create environment-specific overrides for testing
4. Self-Targeting Best Practices
- Clear overrides after testing
- Use meaningful user IDs for team collaboration
- Document override purposes in team communications
5. Audit and Compliance
- Use
get_feature_audit_log_history
for compliance tracking - Tag features appropriately for organization
- Include descriptions for documentation
Architecture & Implementation
Both the local and remote MCP servers share:
- Common Tools: All tool implementations in
src/mcp/tools/
- Schemas & Validation: Shared Zod schemas for input/output validation
- API Clients: Both implement the
IDevCycleApiClient
interface - Error Handling: Consistent error messages and handling across implementations
Key differences:
- Authentication: Local uses API keys/CLI auth, Remote uses OAuth 2.0
- Transport: Local uses stdio, Remote uses SSE/HTTP
- State Storage: Local uses file system, Remote uses Durable Objects
Notes on Environments
- Dedicated environment tools are not exposed via MCP. Use
get_current_project
orselect_project
to retrieve environments and SDK keys for the selected project.
Development & Local Testing
For local development and testing of the MCP server:
Running from Source
# Clone the repository
git clone https://github.com/DevCycleHQ/cli.git
cd cli
# Install dependencies
yarn install
# Build the project
yarn build
# Create a local package
npm pack
# Install the package globally (replace with actual filename)
npm install -g devcycle-cli-*.tgz
# Run the MCP server
dvc-mcp
Alternative: Direct Node Execution
If you prefer to run directly without installing globally:
# After building, run the MCP server directly
node dist/mcp/index.js
Testing with AI Assistants
For local testing, update your AI assistant configuration to point to the local build:
{
"mcpServers": {
"devcycle": {
"command": "node",
"args": ["/path/to/cli/dist/mcp/index.js"]
}
}
}
Debug Logging
The MCP server logs all operations to stderr, which can be viewed in:
- Cursor: Developer Tools console
- Claude Desktop: Log files in the application support directory