# 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

```python
@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.*