6 Principles for Building an Effective MCP Server

Instead of returning entire documents, split your content into smaller, focused fragments. Each fragment should address a specific concept or use case, making it easier for agents to find relevant information quickly.

// Instead of returning entire SDK documentation in one response
{
  "dotnet-sdk-complete": "All .NET SDK documentation (5000+ lines)..."
}

// Fragment by use case and query intent
{
  "dotnet-sdk-installation": "Install via NuGet: dotnet add package...",
  "dotnet-sdk-initialization": "Initialize FBClient with config...",
  "dotnet-sdk-boolean-flags": "Evaluate boolean flags: client.BoolVariation...",
  "dotnet-sdk-user-targeting": "Target users with custom properties...",
  "dotnet-sdk-json-flags": "Work with JSON flags: client.JsonVariation...",
  "dotnet-sdk-best-practices": "Best practices: singleton pattern..."
}

// Each fragment matches specific query patterns:
// "how to install?" → returns dotnet-sdk-installation
// "how to evaluate flags?" → returns relevant evaluation fragments
// "show me examples" → returns code-heavy fragments

By fragmenting content, different query styles (e.g., "What is X?" vs "How to use X?" vs "Show me examples of X") can retrieve precisely tailored responses without overwhelming the agent with unnecessary information.

When a single tool tries to solve 100 different problems, it becomes inefficient and confusing. Instead, implement a routing layer that directs queries to specialized sub-tools based on intent, category, or domain.

// FeatBit MCP Server tool structure
tool: "featbit-docs"
parameters: {
  sdk: "dotnet" | "javascript" | "python" | "java" | "go",
  category: "installation" | "usage" | "best-practices" | "examples",
  query: "user's specific question"
}

// Routing logic:
Query: "How to initialize FeatBit in .NET?"
→ Route to: sdk=dotnet, category=usage
→ Returns: Initialization code + configuration options

Query: "Show me React SDK examples"
→ Route to: sdk=javascript, category=examples  
→ Returns: React-specific code samples

Query: "Best practices for feature flag lifecycle"
→ Route to: category=best-practices (SDK-agnostic)
→ Returns: Lifecycle management guidance

// This prevents a single tool from handling:
// - 6 different SDKs × 4 categories × dozens of topics = chaos
// - Better: 24 focused endpoints with precise context

Think of it as a well-organized library with clear sections. Instead of searching through everything, you first go to the right section (API reference, tutorials, examples), then find specific content.

Complex questions often require information from multiple documents or sections. Instead of forcing agents to make multiple queries, compose comprehensive answers by extracting and combining relevant fragments from various sources.

Query: "How do I implement percentage rollout in ASP.NET Core?"

FeatBit MCP composes from multiple sources:

1. Concept (from docs/concepts/percentage-rollout.md):
   "Percentage rollout gradually releases features to a subset of users..."

2. .NET SDK Installation (from docs/sdk/dotnet/installation.md):
   "dotnet add package FeatBit.ServerSdk --version 2.x.x"

3. SDK Initialization (from docs/sdk/dotnet/initialization.md):
   var client = new FBClient(envSecret, config);

4. Rollout Code (from docs/sdk/dotnet/targeting.md):
   var user = FBUser.Builder("user-key")
       .Name("John Doe")
       .Custom("plan", "pro")
       .Build();
   var showFeature = client.BoolVariation("new-checkout", user, false);

5. ASP.NET Integration (from examples/aspnet-core/integration.cs):
   services.AddSingleton<IFBClient>(sp => fbClient);
   // Use dependency injection...

6. Best Practices (from guides/rollout-best-practices.md):
   - Start with 5-10% of users
   - Monitor metrics before increasing
   - Keep rollout flags temporary

Result: Complete implementation guide with context, code, and advice

Like assembling a puzzle, composition brings together pieces from different documents to create a coherent, comprehensive answer that addresses all aspects of the question.

When multiple documents contain similar or overlapping information, naive retrieval can return repetitive content. Implement deduplication logic to identify and merge redundant information, presenting only unique, non-overlapping content to the agent.

// Problem: SDK docs repeat common concepts
Query: "How to initialize FeatBit SDK?"

// Retrieved from multiple SDK docs (redundant):
- .NET SDK: "Initialize FBClient with environment secret and config..."
- JavaScript SDK: "Initialize FBClient with envSecret and options..."
- Python SDK: "Initialize fb_client with env_secret and configuration..."
- Java SDK: "Initialize FBClient with environment secret and config..."

// After orthogonalization:
Core concept (presented once):
"Initialize FeatBit client with your environment secret (from dashboard) 
and optional configuration for custom streaming/event URLs."

Language-specific variations (unique parts only):
- .NET: var client = new FBClient(envSecret, config);
- JavaScript: const client = new FBClient(envSecret, options);
- Python: client = FBClient(env_secret, config)
- Java: FBClient client = new FBClientImp(envSecret, config);

// Deduplication techniques:
1. Extract common patterns across SDKs
2. Present shared concepts once with priority:
   Official docs > SDK docs > Examples > Community
3. Show language-specific syntax separately
4. Use semantic similarity (embeddings) to detect duplicates

Orthogonality ensures each piece of information is independent and non-redundant, similar to orthogonal vectors in mathematics that point in completely different directions.

Not all queries are perfect on the first try. Implement mechanisms that enable agents to refine their queries through multiple iterations, learning from previous responses to ask better questions.

// Pattern 1: URL References for Deeper Exploration
Query: "Tell me about FeatBit targeting"
Response: {
  "summary": "FeatBit supports user targeting with custom attributes, 
             rules, and percentage rollouts...",
  "documentation": "https://docs.featbit.co/sdk/user-targeting",
  "examples": [
    "https://github.com/featbit/featbit-samples/tree/main/samples/deno-http-server",
    "https://github.com/featbit/featbit-samples/tree/main/samples/csharp-wpf-demo"
  ],
  "hint": "Ask about specific targeting strategies for code examples"
}

// Pattern 2: Iterative Refinement
Query: "How to use feature flags?"
Response: {
  "answer": "Feature flags can be used in multiple ways...",
  "clarifying_questions": [
    "Which programming language are you using? (.NET, JavaScript, Python, Java, Go)",
    "Are you building a web app, mobile app, or backend service?",
    "Do you need boolean toggles, string variations, or JSON configs?"
  ],
  "next_steps": "Specify your tech stack for precise SDK guidance"
}

// Pattern 3: Progressive Disclosure
First query: "Setup FeatBit"
Response: Installation steps + "Next: Initialize the SDK"

Agent re-queries: "Initialize SDK"
Response: Initialization code + "Next: Evaluate your first flag"

Agent re-queries: "Evaluate flag"
Response: Evaluation examples + "Next: Implement user targeting"

// Pattern 4: Incomplete Results Hint
{
  "partial_answer": "Here's how to install FeatBit SDK...",
  "note": "This covers installation only. For initialization and usage, 
          query 'how to initialize FeatBit SDK' and 'how to evaluate flags'"
}

Recall transforms your MCP server from a static knowledge base into an interactive assistant that guides agents toward better questions and more precise answers.

Complex questions often require information from multiple tools or domains. Design your MCP server ecosystem so that tools can reference each other, guiding agents to complementary information sources when needed.

// FeatBit MCP integrates with Context7 ecosystem

// Pattern 1: Reference Other Context7 Libraries
From featbit-mcp tool:
{
  "answer": "FeatBit integrates with ASP.NET Core via dependency injection...",
  "related_mcp_servers": {
    "microsoft-docs": "For ASP.NET Core DI patterns, query @microsoft/docs",
    "aspnet-core-samples": "For complete ASP.NET examples, check Context7"
  }
}

// Pattern 2: Progressive Learning Path
Agent query: "Build feature flag system"

Step 1 - Concepts (featbit-mcp):
  "Feature flags enable runtime control of features..."
  → Suggests: "Next, learn about FeatBit installation"

Step 2 - Installation (featbit-mcp):
  "Install via NuGet/npm/pip..."
  → Suggests: "Next, initialize the SDK with your environment key"

Step 3 - SDK Setup (featbit-mcp):
  "var client = new FBClient(envSecret, config);"
  → Suggests: "Next, evaluate flags with user context"

Step 4 - Flag Evaluation (featbit-mcp):
  "client.BoolVariation('feature-key', user, false);"
  → Suggests: "For ASP.NET Core integration, query @microsoft/docs"

Step 5 - Framework Integration (microsoft-docs MCP):
  "Register IFBClient in DI container..."
  → Suggests: "Return to @featbit for advanced targeting"

// Pattern 3: Complementary Tool Suggestions
From featbit-mcp (deployment question):
{
  "answer": "FeatBit can be self-hosted or cloud-deployed...",
  "note": "For Docker/Kubernetes deployment specifics, consider:",
  "suggested_tools": [
    "@docker/docs - Docker containerization patterns",
    "@kubernetes/docs - K8s deployment strategies",
    "@azure/docs - Azure Container Apps deployment"
  ]
}

// Pattern 4: Real-World Cross-Tool Workflow
User: "Set up FeatBit with React and Azure"

1. @featbit → JavaScript SDK installation
2. @react/docs → React hooks patterns (via Context7)
3. @featbit → Custom hook for feature flags
4. @azure/docs → Azure Static Web Apps deployment
5. @featbit → Environment variable configuration
6. @microsoft/docs → CI/CD with GitHub Actions

Each tool recognizes its boundaries and hands off seamlessly

Cross-tool interaction creates a mesh of knowledge where agents can naturally navigate from high-level concepts to implementation details to practical examples, following the logical flow of learning.