Building a Production-Ready MCP Server for AI Agents to Manage Feature Flags

devcycle · Tech · 2025 · source Agentic: yes · promotional bias: med · source-backed · extracted with prompt 0.5.4 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: MCP server for feature-flag management inside AI coding workflows

DevCycle needed to turn a compelling but unreliable hackathon MCP demo into a production-ready remote MCP server that lets AI coding agents create, inspect, promote, target, and clean up feature flags without leaving the developer's coding workflow.

Constraints:

The hackathon version failed regularly
AI agents used wrong tools when schemas lacked enough context
Bad error handling caused hallucinated fixes and circular recovery attempts
Too many MCP tools consumed context and increased wrong-tool risk
Authentication for a new MCP standard needed to integrate with existing systems
Local MCP installation patterns raised filesystem and permission risks

Architecture

DevCycle adapted its existing CLI/API surface into a production MCP server with carefully described input schemas, descriptive structured error responses, pruned and higher-level tool calls, OAuth hosted through Cloudflare Workers, Durable Objects for per-user session/project state, and a remote HTTP/SSE architecture. The result lets AI coding agents manage feature flags as part of everyday editor prompts while staying scoped by permissions and preserving developer flow.

Diagram confidence: reconstructed (reconstructed from prose).

flowchart LR
  developer-ide[Developer IDE] --> ai-coding-agent[AI Coding Agent]
  ai-coding-agent --> devcycle-mcp-server[DevCycle MCP Server]
  devcycle-mcp-server --> input-schema-layer[Input Schema Layer]
  devcycle-mcp-server --> tool-catalog[Tool Catalog]
  devcycle-mcp-server --> cloudflare-workers-host[Cloudflare Workers Host]
  cloudflare-workers-host --> oauth-flow[OAuth Flow]
  cloudflare-workers-host --> durable-object-session-store[Durable Object Session Store]
  durable-object-session-store --> devcycle-feature-api[DevCycle Feature API]
  devcycle-mcp-server --> devcycle-feature-api
  devcycle-feature-api --> error-response-layer[Error Response Layer]
  error-response-layer --> devcycle-mcp-server

Drag to pan · scroll or use +/− to zoom · reconstructed from the source's described component topology

Components

Component	Role	Interacts with
`AI Coding Agent`	Claude or other coding assistant that calls MCP tools from the developer workflow.	`Developer IDE`, `DevCycle MCP Server`
`Developer IDE`	Coding environment where developers ask natural-language prompts and remain in flow.	`AI Coding Agent`
`DevCycle MCP Server`	Remote MCP interface exposing selected feature-flag workflows to AI agents.	`AI Coding Agent`, `Input Schema Layer`, `Tool Catalog`, `Cloudflare Workers Host`, `DevCycle Feature API`
`Input Schema Layer`	Zod-style schema descriptions that guide tool selection and argument construction.	`DevCycle MCP Server`
`Error Response Layer`	Structured descriptive API errors that help agents self-correct.	`DevCycle MCP Server`, `DevCycle Feature API`
`Tool Catalog`	Pruned set of higher-level MCP tools for feature-flag workflows.	`DevCycle MCP Server`
`Cloudflare Workers Host`	Remote MCP hosting layer that makes OAuth and remote installation easier.	`DevCycle MCP Server`, `OAuth Flow`, `Durable Object Session Store`
`OAuth Flow`	Web-standard authentication and permission scoping for remote MCP access.	`Cloudflare Workers Host`
`Durable Object Session Store`	Per-user session state including selected DevCycle project for subsequent tool calls.	`Cloudflare Workers Host`, `DevCycle Feature API`
`DevCycle Feature API`	Underlying API for creating, targeting, promoting, archiving, and listing feature flags.	`DevCycle MCP Server`, `Error Response Layer`, `Durable Object Session Store`

Data flow

A developer asks an AI agent to perform a feature-flag workflow in the editor. The agent chooses a DevCycle MCP tool using schema descriptions, calls the remote MCP server, authenticates through OAuth, uses Durable Object session state to know the selected DevCycle project, invokes DevCycle feature-flag APIs, receives descriptive errors when API rules are violated, and self-corrects or completes the feature-flag action.

4 supporting quotes

“take our existing CLI interface, which already has authentication and most of our API calls, and adapt it to work as an MCP server.”article, stated

“input schemas that properly define your API are critical. The input schemas (and descriptions) are your AI agent's primary context when deciding which tool to call and the data to call the tool with. AI agents can infer reasonably well from the input schema, but in certain places,”article, stated

“Conversely though, good, descriptive error responses can solve for a lot of other problems with your MCP. If you provide detailed error responses from your APIs, that are helpful, the agent can generally one-shot fix issues in its chain of reasoning.”article, stated

“For example, we store which DevCycle project you are interfacing with for the MCP, and have tool calls that let you select between different projects in your organization.”article, stated

Why this architecture

DevCycle optimized for production agent behavior rather than maximum API exposure. Schemas and errors became part of the agent's reasoning context, pruning reduced context-window pressure, higher-level tools simplified workflows, and remote OAuth-scoped hosting avoided the security pitfalls of local MCP servers with broad filesystem access.

4 supporting quotes

“Without a good input schema, we found that AI agents would regularly try to use the wrong tool, causing errors or even taking the agents down unintended paths.”article, stated

“Pruning your tool calls is essential; not every API function you have makes sense to be available as an MCP tool call”article, stated

“Counter-intuitively to API best practices, larger tool call surfaces that can combine multiple API functions into a single MCP tool call are preferable. It reduces the number of tools your MCP needs to expose and likely reduces the amount of AI context you are using up to describe your MCP tools.”article, stated

“Remote MCP servers are easier and safer for users to install; you just need to set a URL, and you're up and running. If you are using OAuth for authentication, your users use a web-standard authentication API through which you can properly scope the permissions your MCP server has access to.”article, stated

Models used: AI coding agents · Claude

Scale

DevCycle's starting point was a hackathon prototype adapted from an existing CLI.
“When we started building our MCP server, it began as a simple hackathon project: take our existing CLI interface, which already has authentication and most of our API calls, and adapt it to work as an MCP server.”article, stated
DevCycle had over a decade of SDK-based SaaS experience informing the MCP onboarding flow.
“As a team that has built SDK-based SaaS services for over a decade, this approach addresses two persistent challenges: getting customers to install and update SDKs and streamlining the onboarding process.”article, stated
The MCP tooling supports routine development flows such as creating flags, self-targeting, promoting to staging, and enabling production for internal users.
“create a new variable and feature for you in DevCycle, and self-target you into that flag to initially test it locally.”article, stated

Alternatives considered (roads not taken)

Expose the full API surface as MCP tools

Rejected because: Every tool consumes context, raises wrong-tool risk, and some destructive project-level actions are unlikely to be appropriate for agents.

“Pruning your tool calls is essential; not every API function you have makes sense to be available as an MCP tool call, and every new MCP tool eats up more of your AI context window.”article, stated

“not every API function you have makes sense to be available as an MCP tool call, and every new MCP tool eats up more of your AI context window. We had to ask ourselves, do we think someone really wants/needs to be able to delete whole projects from an MCP tool call? Once we got past the”article, stated

Rely on traditional terse API errors

Rejected because: Agents hallucinated fixes and looped when errors were not descriptive.

“Bad error handling can break everything. The AI agent will fail as soon as it runs into an error without a very descriptive error response. Most of the time, it will just start hallucinating new data to fix the error and get into circles, chasing its own tail.”article, stated

“Most of the time, it will just start hallucinating new data to fix the error and get into circles, chasing its own tail. Conversely though, good, descriptive error responses can solve for a lot of other problems with your MCP.”article, stated

Use local npx-installed MCP servers

Rejected because: Local install patterns can grant broad filesystem access, while remote OAuth scopes permissions and time-limited tokens.

“providing an npx -y some-mcp-script to install a local MCP server with full access to your computer's file system is rife with security concerns”article, stated

“common practice for local MCP servers of providing an npx -y some-mcp-script to install a local MCP server with full access to your computer's file system is rife with security concerns, compared to an HTTP / SSE-based remote MCP server, scoped using permissions and time-scoped OAuth tokens.”article, stated

Use large output schemas for more tool context

Rejected because: The token cost was likely not worth the benefit compared with concise tool descriptions.

“Output schemas can help provide more context to the AI when it chooses which tool call to make. However, the token cost of large output schemas is likely not worth the minimal benefit, when most of the output's context can be provided with a simple statement in the tool call's description.”article, stated

“However, the token cost of large output schemas is likely not worth the minimal benefit, when most of the output's context can be provided with a simple statement in the tool call's description.”article, stated

Patterns

`tool-use-orchestration` (mcp-integration)

The MCP server lets coding agents create, target, promote, inspect, and clean up DevCycle feature flags from editor prompts.

“agents could create new feature flags, investigate incidents, clean up stale flags, and help with QA, all with natural language.”article, stated

“wrap this new functionality in a DevCycle flag”article, stated

`structured-output-contract` (agent-interface)

Input schemas and descriptions encode the tool-call contract the agent uses to select tools and arguments.

“Good input schemas that properly define your API are critical.”article, stated

“.describe() statements on your schema parameters will help push the AI agent in the right direction.”article, stated

`fallback-degradation` (agent-recovery)

Detailed API errors act as feedback that lets agents recover from invalid requests instead of hallucinating fixes.

“good, descriptive error responses can solve for a lot of other problems with your MCP.”article, stated

“the agent can generally one-shot fix issues in its chain of reasoning.”article, stated

`context-compaction` (tool-surface-management)

DevCycle pruned tool calls and combined API functions into larger workflow tools to reduce MCP context usage.

“larger tool call surfaces that can combine multiple API functions into a single MCP tool call are preferable.”article, stated

“likely reduces the amount of AI context you are using up to describe your MCP tools.”article, stated

`safety-policy-enforcement` (remote-mcp-security)

The production MCP uses remote OAuth-scoped access instead of local filesystem-wide MCP installs.

“If you are using OAuth for authentication, your users use a web-standard authentication API”article, stated

“properly scope the permissions your MCP server has access to.”article, stated

`agent-memory` (session-state)

Durable Objects store the selected DevCycle project so later tool calls do not force the agent to remember it.

“it also lets you store other session state data.”article, stated

“your MCP session has already selected a project, and we have stored that state in the Cloudflare Durable Object”article, stated

Tradeoffs

Host MCP remotely

Chose HTTP/SSE remote MCP with OAuth over local npx MCP server installs.

Rationale: Remote hosting is easier to install and scopes permissions better than local filesystem-accessing servers.

“Remote MCP servers are easier and safer for users to install; you just need to set a URL”article, stated

“local MCP server with full access to your computer's file system is rife with security concerns”article, stated

Prune and combine MCP tools

Chose fewer higher-level workflow tools over one MCP tool for every API function.

Rationale: Fewer, broader tools reduce context pressure and wrong-tool selection.

“not every API function you have makes sense to be available as an MCP tool call”article, stated

“larger tool call surfaces that can combine multiple API functions into a single MCP tool call are preferable.”article, stated

Use Cloudflare Workers and Durable Objects

Chose Cloudflare-hosted remote MCP with durable session state over custom auth/session implementation from scratch.

Rationale: Cloudflare made OAuth mostly painless and Durable Objects provided scalable per-user MCP session state.

“using Cloudflare Workers + Durable Objects to host the remote MCP server made the OAuth implementation mostly painless.”article, stated

“managing the OAuth session state in a Durable Object for all of a user's requests is a good, scalable solution for us.”article, stated

Gotchas (what bit them)

A compelling MCP demo can still fail regularly.

Root cause: The hackathon build lacked production-grade schema, error, auth, tool-surface, and workflow hardening.

Resolution: DevCycle iterated through schema descriptions, structured errors, tool pruning, OAuth, durable session state, and remote hosting.

“We thought the demo was cool, but it was rough around the edges and failed regularly”article, stated

“it would take quite a bit of iteration to make it production-ready.”article, stated

Weak schemas send agents down the wrong path.

Root cause: The schema is the agent's main context for tool selection and argument filling.

Resolution: DevCycle added explicit parameter descriptions to guide tool usage.

“AI agents would regularly try to use the wrong tool, causing errors or even taking the agents down unintended paths.”article, stated

“AI agents can infer reasonably well from the input schema, but in certain places, .describe() statements”article, stated

Bad errors trigger hallucinated recovery loops.

Root cause: Agents need concrete information about what failed and how to fix it.

Resolution: DevCycle returns detailed error type, message, tool name, suggestions, and timestamp.

“The AI agent will fail as soon as it runs into an error without a very descriptive error response.”article, stated

“Most of the time, it will just start hallucinating new data to fix the error and get into circles”article, stated

Tool sprawl wastes agent context.

Root cause: Each exposed MCP tool needs description/context, and many agent platforms restrict or warn on too many tools.

Resolution: DevCycle minimized the exposed tool count and made higher-level tool calls.

“every new MCP tool eats up more of your AI context window.”article, stated

“Many AI Agent platforms restrict the number of MCP tools installed”article, stated

Evaluation

DevCycle evaluated production readiness through trial-and-error hardening, agent success creating complex features, observed wrong-tool/error behavior, and workflow fit inside coding-agent prompts.

Metrics: feature creation success rate · wrong-tool attempts · agent self-correction after errors · MCP tool count · OAuth/session reliability · developer workflow adoption

3 supporting quotes

“To get the MCP server from hackathon "working" code to a shippable product took a lot of learning through trial and error.”article, stated

“they had an extremely high success rate generating features with complex targeting rules all through a natural language interaction”article, stated

“with detailed input schemas combined with descriptive error responses”summary, stated

Outcomes

DevCycle moved from a hackathon MCP prototype to a production-ready remote MCP server.
Agents can create feature flags, investigate incidents, self-target, promote features, enable production targeting, and clean stale flags through natural language.
Structured schemas and descriptive errors enabled high success on complex feature creation.
Remote Cloudflare Workers hosting plus Durable Objects solved OAuth and session-state needs.
The MCP kept developers in coding context rather than forcing dashboard switching.

The article reports a hackathon-to-production transition, support for multi-step feature-flag workflows, Durable Object session state across all user requests, and DevCycle's decade-plus SDK/SaaS experience; the ZenML summary additionally reports roughly 3x more users reaching SDK installation than the prior onboarding flow.