managing-apps/assets/documentation/MCP-Architecture.md

MCP (Model Context Protocol) Architecture

Overview

This document describes the Model Context Protocol (MCP) architecture for the Managing trading platform. The architecture uses a dual-MCP approach: one internal C# MCP server for proprietary tools, and one open-source Node.js MCP server for community use.

Architecture Decision

Selected Option: Option 4 - Two MCP Servers by Deployment Model

• C# MCP Server: Internal, in-process, proprietary tools
• Node.js MCP Server: Standalone, open-source, community-distributed

Rationale

Why Two MCP Servers?

1. Proprietary vs Open Source Separation

   • C# MCP: Contains proprietary business logic, trading algorithms, and internal tools
   • Node.js MCP: Public tools that can be open-sourced and contributed to by the community

2. Deployment Flexibility

   • C# MCP: Runs in-process within the API (fast, secure, no external access)
   • Node.js MCP: Community members install and run independently using their own API keys

3. Community Adoption

   • Node.js MCP can be published to npm
   • Community can contribute improvements
   • Works with existing Node.js MCP ecosystem

4. Security & Access Control

   • Internal tools stay private
   • Public tools use ManagingApiKeys for authentication
   • Each community member uses their own API key

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│ Your Infrastructure                                          │
│                                                              │
│  ┌──────────────┐      ┌──────────────┐                    │
│  │ LLM Service  │─────▶│ C# MCP       │                    │
│  │ (Your API)   │      │ (Internal)   │                    │
│  └──────────────┘      └──────────────┘                    │
│         │                                                     │
│         │ HTTP + API Key                                     │
│         ▼                                                     │
│  ┌─────────────────────────────────────┐                    │
│  │ Public API Endpoints                │                    │
│  │ - /api/public/agents                │                    │
│  │ - /api/public/market-data           │                    │
│  │ - (Protected by ManagingApiKeys)    │                    │
│  └─────────────────────────────────────┘                    │
└─────────────────────────────────────────────────────────────┘
                    ▲
                    │ HTTP + API Key
                    │
┌─────────────────────────────────────────────────────────────┐
│ Community Infrastructure (Each User Runs Their Own)         │
│                                                              │
│  ┌──────────────┐      ┌──────────────┐                    │
│  │ LLM Client   │─────▶│ Node.js MCP  │                    │
│  │ (Claude, etc)│      │ (Open Source)│                    │
│  └──────────────┘      └──────────────┘                    │
│                              │                               │
│                              │ Uses ManagingApiKey           │
│                              │                               │
│                              ▼                               │
│                    ┌─────────────────┐                       │
│                    │ API Key Config  │                       │
│                    │ (User's Key)    │                       │
│                    └─────────────────┘                       │
└─────────────────────────────────────────────────────────────┘

Component Details

1. C# MCP Server (Internal/Proprietary)

Location: src/Managing.Mcp/

Characteristics:

• Runs in-process within the API
• Contains proprietary trading logic
• Direct access to internal services via DI
• Fast execution (no network overhead)
• Not exposed externally

Tools:

• Internal trading operations
• Proprietary analytics
• Business-critical operations
• Admin functions

Implementation:

[McpServerToolType]
public static class InternalTradingTools
{
    [McpServerTool, Description("Open a trading position (internal only)")]
    public static async Task<object> OpenPosition(
        ITradingService tradingService,
        IAccountService accountService,
        // ... internal services
    ) { }
}

2. Node.js MCP Server (Open Source/Community)

Location: src/Managing.Mcp.Nodejs/ (future)

Characteristics:

• Standalone Node.js package
• Published to npm
• Community members install and run independently
• Connects to public API endpoints
• Uses ManagingApiKeys for authentication

Tools:

• Public agent summaries
• Market data queries
• Public analytics
• Read-only operations

Distribution:

• Published as @yourorg/managing-mcp on npm
• Community members install: npm install -g @yourorg/managing-mcp
• Each user configures their own API key

3. Public API Endpoints

Location: src/Managing.Api/Controllers/PublicController.cs

Purpose:

• Expose safe, public data to community
• Protected by ManagingApiKeys authentication
• Rate-limited per API key
• Audit trail for usage

Endpoints:

• GET /api/public/agents/{agentName} - Get public agent summary
• GET /api/public/agents - List public agents
• GET /api/public/market-data/{ticker} - Get market data

Security:

• API key authentication required
• Only returns public-safe data
• No internal business logic exposed

4. ManagingApiKeys Feature

Status: Not yet implemented

Purpose:

• Authenticate community members using Node.js MCP
• Control access to public API endpoints
• Enable rate limiting per user
• Track usage and analytics

Implementation Requirements:

• API key generation and management
• API key validation middleware
• User association with API keys
• Rate limiting per key
• Usage tracking and analytics

Implementation Phases

Phase 1: C# MCP Server (Current)

Status: To be implemented

Tasks:

• Install ModelContextProtocol NuGet package
• Create Managing.Mcp project structure
• Implement internal tools using [McpServerTool] attributes
• Create in-process MCP server service
• Integrate with LLM service
• Register in DI container

Files to Create:

• src/Managing.Mcp/Managing.Mcp.csproj
• src/Managing.Mcp/Tools/InternalTradingTools.cs
• src/Managing.Mcp/Tools/InternalAdminTools.cs
• src/Managing.Application/LLM/IMcpService.cs
• src/Managing.Application/LLM/McpService.cs

Phase 2: Public API Endpoints

Status: To be implemented

Tasks:

• Create PublicController with public endpoints
• Implement ApiKeyAuthenticationHandler
• Create [ApiKeyAuth] attribute
• Design public data models (only safe data)
• Add rate limiting per API key
• Implement usage tracking

Files to Create:

• src/Managing.Api/Controllers/PublicController.cs
• src/Managing.Api/Authentication/ApiKeyAuthenticationHandler.cs
• src/Managing.Api/Filters/ApiKeyAuthAttribute.cs
• src/Managing.Application/Abstractions/Services/IApiKeyService.cs
• src/Managing.Application/ApiKeys/ApiKeyService.cs

Phase 3: ManagingApiKeys Feature

Status: Not yet ready

Tasks:

• Design API key database schema
• Implement API key generation
• Create API key management UI/API
• Add API key validation
• Implement rate limiting
• Add usage analytics

Database Schema (proposed):

CREATE TABLE api_keys (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    key_hash VARCHAR(255) NOT NULL,
    name VARCHAR(255),
    created_at TIMESTAMP,
    last_used_at TIMESTAMP,
    expires_at TIMESTAMP,
    rate_limit_per_hour INTEGER,
    is_active BOOLEAN
);

Phase 4: Node.js MCP Server (Future/Open Source)

Status: Future - after ManagingApiKeys is ready

Tasks:

• Create Node.js project structure
• Implement MCP server using @modelcontextprotocol/sdk
• Create API client with API key support
• Implement public tool handlers
• Create configuration system
• Write documentation
• Publish to npm

Files to Create:

• src/Managing.Mcp.Nodejs/package.json
• src/Managing.Mcp.Nodejs/index.js
• src/Managing.Mcp.Nodejs/tools/public-tools.ts
• src/Managing.Mcp.Nodejs/api/client.ts
• src/Managing.Mcp.Nodejs/config/config.ts
• src/Managing.Mcp.Nodejs/README.md

Service Integration

LLM Service Integration

Your internal LLM service only uses the C# MCP:

public class LLMService : ILLMService
{
    private readonly IMcpService _internalMcpService; // C# only
    
    public async Task<LLMResponse> GenerateContentAsync(...)
    {
        // Only use internal C# MCP
        // Community uses Node.js MCP separately
    }
}

Unified Service (Optional)

If you need to combine both MCPs in the future:

public class UnifiedMcpService : IUnifiedMcpService
{
    private readonly IMcpService _internalMcpService;
    private readonly IMcpClientService _externalMcpClientService;
    
    // Routes tools to appropriate MCP based on prefix
    // internal:* -> C# MCP
    // public:* -> Node.js MCP (if needed internally)
}

Configuration

C# MCP Configuration

// appsettings.json
{
  "Mcp": {
    "Internal": {
      "Enabled": true,
      "Type": "in-process"
    }
  }
}

Node.js MCP Configuration (Community)

// ~/.managing-mcp/config.json
{
  "apiUrl": "https://api.yourdomain.com",
  "apiKey": "user-api-key-here"
}

Or environment variables:

• MANAGING_API_URL
• MANAGING_API_KEY

Benefits

For Your Platform

1. No Hosting Burden: Community runs their own Node.js MCP instances
2. API Key Control: You control access via ManagingApiKeys
3. Scalability: Distributed across community
4. Security: Internal tools stay private
5. Analytics: Track usage per API key

For Community

1. Open Source: Can contribute improvements
2. Easy Installation: Simple npm install
3. Privacy: Each user uses their own API key
4. Flexibility: Can customize or fork
5. Ecosystem: Works with existing Node.js MCP tools

Security Considerations

Internal C# MCP

• Runs in-process, no external access
• Direct service access via DI
• No network exposure
• Proprietary code stays private

Public API Endpoints

• API key authentication required
• Rate limiting per key
• Only public-safe data returned
• Audit trail for all requests

Node.js MCP

• Community members manage their own instances
• Each user has their own API key
• No access to internal tools
• Can be audited (open source)

Future Enhancements

1. MCP Registry: List community-created tools
2. Tool Marketplace: Community can share custom tools
3. Analytics Dashboard: Usage metrics per API key
4. Webhook Support: Real-time updates via MCP
5. Multi-tenant Support: Organizations with shared API keys

References

• Model Context Protocol Specification
• C# SDK Documentation
• Node.js SDK Documentation

Related Documentation

• Architecture.drawio - Overall system architecture
• Workers processing/ - Worker architecture details

Status

• C# MCP Server: Planning
• Public API Endpoints: Planning
• ManagingApiKeys: Not yet ready
• Node.js MCP Server: Future (after ManagingApiKeys)

Notes

• The Node.js MCP will NOT be hosted by you - community members run it themselves
• Each community member uses their own ManagingApiKey
• Internal LLM service only uses C# MCP (in-process)
• Public API endpoints are the bridge between community and your platform