ColaFlow/docs/mcp-sdk-phase3-summary.md

MCP SDK Phase 3: Runtime Test Summary

Date: 2025-11-09 Status: ⚠️ BLOCKED - Architecture Decision Required

---

TL;DR

The Microsoft MCP SDK (ModelContextProtocol v0.4.0-preview.3) is registered in DI but NOT actually used at runtime. ColaFlow has a custom HTTP-based MCP implementation that works independently of the SDK.

---

Key Findings

🔴 Critical Issue: SDK Not Functional

// In Program.cs - SDK is registered
builder.Services.AddMcpServer()
    .WithToolsFromAssembly()
    .WithResourcesFromAssembly();

// But custom handler is used instead
app.UseMcpMiddleware();  // <- Custom implementation, not SDK

Evidence:

• Application uses custom HTTP endpoint /mcp (not SDK's stdio)
• Logs show "MCP Protocol Handler initialized" (custom, not SDK)
• SDK tools (Ping, GetServerTime, GetProjectInfo) are discovered but never called
• No stdio transport (SDK's primary feature)

---

What Works ✅

1. Application Startup: Starts successfully on port 5167
2. Custom MCP Endpoint: /mcp endpoint operational
3. Resource Discovery: 6 resources registered via custom registry
4. API Key Auth: Custom authentication middleware works
5. Health Check: /health endpoint returns 200 OK

---

What Doesn't Work ❌

1. Microsoft MCP SDK: Not integrated with custom handler
2. SDK stdio Transport: Not implemented (only HTTP exists)
3. SDK Tool Discovery: Tools discovered but not exposed
4. Claude Desktop Integration: Impossible (requires stdio)
5. Dependency Injection in SDK Tools: Cannot verify (tools never called)

---

Architecture Mismatch

Expected (SDK):

Claude Desktop → stdio → MCP SDK → Tools/Resources

Actual (Current):

Web Client → HTTP → Custom Handler → Custom Tools/Resources
                     (SDK ignored)

---

Test Results Summary

Component	Expected	Actual	Status
Transport	stdio	HTTP	❌ Mismatch
Endpoint	stdin/stdout	/mcp	❌ Mismatch
Tool Discovery	SDK .WithToolsFromAssembly()	Custom registry	⚠️ Partial
Resource Discovery	SDK .WithResourcesFromAssembly()	Custom registry	✅ Works (custom)
Authentication	SDK built-in	Custom API Key	✅ Works (custom)
DI in Tools	SDK constructor injection	N/A	❌ Untestable

---

Critical Questions

Q1: Should we use Microsoft MCP SDK at all?

Option A: Remove SDK (Recommended for short-term)

• ✅ Simpler architecture
• ✅ Custom implementation is working
• ❌ No Claude Desktop integration
• ❌ Non-standard MCP protocol

Option B: Use SDK Properly (Recommended for long-term)

• ✅ Standard MCP protocol
• ✅ Claude Desktop integration
• ❌ Requires stdio transport implementation
• ❌ More complex (hybrid approach)

Option C: Hybrid (Best of both worlds)

• ✅ HTTP for web clients (current)
• ✅ stdio for Claude Desktop (new)
• ✅ Shared tool/resource registry
• ❌ Most complex to implement

---

Recommendation

Short-term: Option A - Remove SDK

// Remove from Program.cs
// builder.Services.AddMcpServer()
//     .WithToolsFromAssembly()
//     .WithResourcesFromAssembly();

// Remove from ColaFlow.API.csproj
// <PackageReference Include="ModelContextProtocol" Version="0.4.0-preview.3" />

// Keep custom implementation
app.UseMcpMiddleware();  // This works

Reasoning:

• SDK is not being used
• Custom implementation is functional
• Reduces confusion and maintenance burden
• Can re-evaluate SDK in future when it's more mature (currently preview)

Long-term: Option C - Hybrid

// Keep custom HTTP for web
app.MapPost("/mcp", CustomMcpHandler);

// Add SDK stdio for Claude Desktop
if (app.Environment.IsDevelopment())
{
    app.UseStdioMcpServer();  // <- To be implemented
}

Benefits:

• Best user experience for all clients
• Standard MCP protocol support
• Flexibility for different use cases

---

Next Actions

1. Decision Required: Choose Option A, B, or C
2. If Option A (Remove SDK):
   • Remove NuGet package
   • Remove SDK registration
   • Update documentation
   • Continue with custom implementation
3. If Option B/C (Use SDK):
   • Implement stdio transport
   • Bridge SDK tools to custom handler
   • Test with Claude Desktop
   • Document both approaches

---

Files Generated

• ✅ docs/mcp-sdk-phase3-runtime-test-report.md - Full detailed report
• ✅ docs/mcp-sdk-phase3-summary.md - This summary
• ✅ scripts/test-mcp-runtime.ps1 - Runtime test script
• ✅ scripts/create-test-api-key.ps1 - API key creation script

---

Contact

For questions or decisions, please consult:

• Architect agent (architecture decisions)
• Product Manager (user requirements)
• Backend agent (implementation)

---

Status: Awaiting architecture decision before proceeding to Phase 4