MCP Architecture¶

Model Context Protocol architecture and SDK MCP implementation.

Overview¶

Nova AI uses SDK MCP servers (in-process) for 10-100x performance improvement over stdio MCP:

graph TB
    A[Claude Agent] --> B[SDK MCP Server]
    B --> C[KB Store]
    B --> D[GitHub API]
    B --> E[Memory Store]

    F[No Subprocess] --> B
    G[No Serialization] --> B
    H[Direct Python] --> B

    style B fill:#3f51b5,color:#fff

SDK MCP vs stdio MCP¶

Feature	stdio MCP	SDK MCP	Improvement
Process	Subprocess	In-process	100x faster spawn
Communication	stdio JSON	Direct Python	No serialization
Overhead	850ms	8ms	106x faster
Debugging	Complex	Standard	Normal stack traces
Memory	Separate	Shared	No copies

Architecture¶

SDK MCP Server Structure¶

# src/orchestrator/tools/sdk_mcp_kb_server.py
from anthropic_sdk_mcp import Tool

@Tool(name="search_knowledge_base")
async def search_knowledge_base(
    query: str,
    top_k: int = 5,
    filters: dict | None = None
) -> list[dict]:
    """Search knowledge base with semantic similarity."""
    kb = LocalKB(kb_dir=KB_DIR)
    return kb.query(query, top_k, filters)

Integration with Executor¶

executor = ClaudeSDKExecutor(
    agent_name="orchestrator",
    use_sdk_mcp=True  # Enable SDK MCP
)

# Tools automatically available:
# - search_knowledge_base
# - create_pull_request
# - store_memory

Performance Comparison¶

KB Search¶

stdio MCP (old):

1. Spawn subprocess: 200ms
2. Serialize query: 50ms
3. Search FAISS: 8ms
4. Deserialize results: 92ms
5. Kill subprocess: 500ms
Total: 850ms

SDK MCP (new):

1. Direct Python import: 0ms
2. Search FAISS: 8ms
3. Return results: 0ms
Total: 8ms (106x faster)

GitHub API¶

stdio MCP: 450ms (subprocess overhead) SDK MCP: 45ms (10x faster)

Memory Store¶

stdio MCP: 120ms SDK MCP: 2ms (60x faster)

Available Servers¶

1. Knowledge Base¶

# src/orchestrator/tools/sdk_mcp_kb_server.py
@Tool(name="search_knowledge_base")
async def search_knowledge_base(query: str, top_k: int = 5):
    """Search 11GB FAISS KB."""
    ...

@Tool(name="get_kb_stats")
async def get_kb_stats():
    """Get KB statistics."""
    ...

2. GitHub¶

# src/orchestrator/tools/sdk_mcp_github_server.py
@Tool(name="create_pull_request")
async def create_pull_request(repo: str, title: str, body: str):
    """Create GitHub PR."""
    ...

@Tool(name="create_issue")
async def create_issue(repo: str, title: str, body: str):
    """Create GitHub issue."""
    ...

3. Memory¶

# src/orchestrator/tools/sdk_mcp_memory_server.py
@Tool(name="store_memory")
async def store_memory(key: str, value: Any, scope: str):
    """Store persistent memory."""
    ...

@Tool(name="retrieve_memory")
async def retrieve_memory(key: str, scope: str):
    """Retrieve stored memory."""
    ...

Best Practices¶

Always use SDK MCP - 10-100x faster
No stdio MCP - Deprecated in Nova AI
Direct Python imports - No subprocess overhead
Shared memory - No serialization costs
Standard debugging - Normal Python stack traces

Next Steps¶

MCP Guide Agent System