syndarix/docs/adrs/ADR-001-mcp-integration-architecture.md

ADR-001: MCP Integration Architecture

Status: Accepted Date: 2025-12-29 Deciders: Architecture Team Related Spikes: SPIKE-001

---

Context

Syndarix requires integration with multiple external services (LLM providers, Git, issue trackers, file systems, CI/CD). The Model Context Protocol (MCP) was identified as the standard for tool integration in AI applications. We need to decide on:

1. The MCP framework to use
2. Server deployment pattern (singleton vs per-project)
3. Scoping mechanism for multi-project/multi-agent access

Decision Drivers

• Simplicity: Minimize operational complexity
• Resource Efficiency: Avoid spawning redundant processes
• Consistency: Unified interface across all integrations
• Scalability: Support 10+ concurrent projects
• Maintainability: Easy to add new MCP servers

Considered Options

Option 1: Per-Project MCP Servers

Spawn dedicated MCP server instances for each project.

Pros:

• Complete isolation between projects
• Simple access control (project owns server)

Cons:

• Resource heavy (7 servers × N projects)
• Complex orchestration
• Difficult to share cross-project resources

Option 2: Unified Singleton MCP Servers (Selected)

Single instance of each MCP server type, with explicit project/agent scoping.

Pros:

• Resource efficient (7 total servers)
• Simpler deployment
• Enables cross-project learning (if desired)
• Consistent management

Cons:

• Requires explicit scoping in all tools
• Shared state requires careful design

Option 3: Hybrid (MCP Proxy)

Single proxy that routes to per-project backends.

Pros:

• Balance of isolation and efficiency

Cons:

• Added complexity
• Routing overhead

Decision

Adopt Option 2: Unified Singleton MCP Servers with explicit scoping.

All MCP servers are deployed as singletons. Every tool accepts project_id and agent_id parameters for:

• Access control validation
• Audit logging
• Context filtering

Implementation

MCP Server Registry

Server	Port	Purpose
LLM Gateway	9001	Route LLM requests with failover
Git MCP	9002	Git operations across providers
Knowledge Base MCP	9003	RAG and document search
Issues MCP	9004	Issue tracking operations
File System MCP	9005	Workspace file operations
Code Analysis MCP	9006	Static analysis, linting
CI/CD MCP	9007	Pipeline operations

Framework Selection

Use FastMCP 2.0 for all MCP server implementations:

• Decorator-based tool registration
• Built-in async support
• Compatible with SSE transport
• Type-safe with Pydantic

Tool Signature Pattern

@mcp.tool()
def tool_name(
    project_id: str,   # Required: project scope
    agent_id: str,     # Required: calling agent
    # ... tool-specific params
) -> Result:
    validate_access(agent_id, project_id)
    log_tool_usage(agent_id, project_id, "tool_name")
    # ... implementation

Consequences

Positive

• Single deployment per MCP type simplifies operations
• Consistent interface across all tools
• Easy to add monitoring/logging centrally
• Cross-project analytics possible

Negative

• All tools must include scoping parameters
• Shared state requires careful design
• Single point of failure per MCP type (mitigated by multiple instances)

Neutral

• Requires MCP client manager in FastAPI backend
• Authentication handled internally (service tokens for v1)

Compliance

This decision aligns with:

• FR-802: MCP-first architecture requirement
• NFR-201: Horizontal scalability requirement
• NFR-602: Centralized logging requirement

---

This ADR supersedes any previous decisions regarding MCP architecture.