Skip to content

MCP Servers Guide

Learn how to configure and use Model Context Protocol (MCP) servers in Nova AI.

Overview

Nova AI uses SDK MCP servers (in-process) for maximum performance:

  • 10-100x faster than stdio MCP servers
  • No subprocess overhead - Direct Python imports
  • No serialization - Native Python objects
  • Simpler debugging - Standard Python stack traces
graph LR
    A[Claude Agent] --> B[SDK MCP Server]
    B --> C[KB Store]
    B --> D[GitHub API]
    B --> E[Memory Store]

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

Available MCP Servers

1. Knowledge Base (kb)

Purpose: Semantic search across 11GB FAISS-indexed expert knowledge

Capabilities:

  • Search 37 domain areas (architecture, security, testing, etc.)
  • Semantic similarity search with embeddings
  • Metadata filtering (domain, file type, date)
  • Return relevant chunks with context

Usage:

from src.orchestrator.tools.sdk_mcp_kb_server import search_knowledge_base

# Search for authentication patterns
results = await search_knowledge_base(
    query="JWT authentication best practices",
    top_k=5,
    filters={"domain": "security"}
)

for result in results:
    print(f"Source: {result['file']}")
    print(f"Content: {result['text']}")
    print(f"Score: {result['score']}")

Available Tools:

Tool Description Parameters
search_knowledge_base Semantic search query, top_k, filters
get_kb_stats KB statistics -
list_domains Available domains -

Example Query:

/novaai implement JWT authentication following the patterns in the knowledge base

The orchestrator automatically searches KB and finds:

KB Results:
- /kb/security/jwt-patterns.md (score: 0.94)
- /kb/auth/token-refresh.md (score: 0.89)
- /kb/api/authentication.md (score: 0.85)

2. GitHub (github)

Purpose: GitHub operations (PRs, issues, commits, reviews)

Capabilities:

  • Create and manage pull requests
  • Comment on PRs and issues
  • Create issues
  • Fetch file contents
  • List commits
  • Add PR reviews

Usage:

from src.orchestrator.tools.sdk_mcp_github_server import create_pull_request

# Create PR
pr = await create_pull_request(
    repo="owner/repo",
    title="Add user authentication",
    body="Implements JWT authentication with refresh tokens",
    head="feature/auth",
    base="main"
)

print(f"PR created: {pr['html_url']}")

Available Tools:

Tool Description Parameters
create_pull_request Create new PR repo, title, body, head, base
create_issue Create new issue repo, title, body
add_comment Comment on PR/issue repo, issue_number, body
get_file_contents Fetch file repo, path, ref
list_commits List commits repo, sha, per_page
create_review Add PR review repo, pr_number, event, body

Example:

/novaai review PR #123 and add review comments

3. Memory (memory)

Purpose: Persistent memory across sessions

Capabilities:

  • Store key-value pairs
  • Session-scoped memory
  • Project-scoped memory
  • Automatic cleanup

Usage:

from src.orchestrator.tools.sdk_mcp_memory_server import store_memory, retrieve_memory

# Store decision
await store_memory(
    key="auth_strategy",
    value="JWT with refresh tokens",
    scope="project"
)

# Retrieve later
strategy = await retrieve_memory(key="auth_strategy", scope="project")
print(f"Auth strategy: {strategy}")

Available Tools:

Tool Description Parameters
store_memory Store key-value key, value, scope
retrieve_memory Retrieve value key, scope
list_memory List all keys scope
delete_memory Delete key key, scope

Scopes:

  • session - Current session only
  • project - Entire project (persistent)
  • user - User-specific (future)

Configuration

SDK MCP Setup

SDK MCP servers are automatically enabled in ClaudeSDKExecutor:

from src.orchestrator.claude_sdk_executor import ClaudeSDKExecutor

executor = ClaudeSDKExecutor(
    project_root=Path.cwd(),
    agent_name="orchestrator",
    use_sdk_mcp=True  # Enable SDK MCP (default)
)

MCP Config File

SDK MCP servers are configured in mcp-config.json:

{
  "mcpServers": {
    "kb": {
      "type": "sdk",
      "module": "src.orchestrator.tools.sdk_mcp_kb_server",
      "config": {
        "kb_dir": "kb_store/faiss_metadata",
        "max_results": 10
      }
    },
    "github": {
      "type": "sdk",
      "module": "src.orchestrator.tools.sdk_mcp_github_server",
      "config": {
        "token": "${GITHUB_TOKEN}"
      }
    },
    "memory": {
      "type": "sdk",
      "module": "src.orchestrator.tools.sdk_mcp_memory_server",
      "config": {
        "storage_dir": ".nova/memory"
      }
    }
  }
}

Environment Variables

Required environment variables:

# Anthropic API (required)
export ANTHROPIC_API_KEY="your-key-here"

# GitHub MCP (optional, for PR workflows)
export GITHUB_TOKEN="your-github-token"

# Knowledge Base (optional, custom path)
export NOVA_KB_DIR="kb_store/faiss_metadata"

Knowledge Base Setup

Directory Structure

kb_store/faiss_metadata/
├── manifest.json          # KB metadata
├── metadata.parquet       # Chunk metadata
└── faiss_ivfpq.index     # FAISS index

Verify KB Setup

# Check KB directory exists
ls -la kb_store/faiss_metadata/

# Check manifest
cat kb_store/faiss_metadata/manifest.json

# Check metadata
python -c "import pandas as pd; df = pd.read_parquet('kb_store/faiss_metadata/metadata.parquet'); print(df.info())"

KB Statistics

from src.orchestrator.tools.sdk_mcp_kb_server import get_kb_stats

stats = await get_kb_stats()
print(f"Total chunks: {stats['total_chunks']}")
print(f"Domains: {stats['domains']}")
print(f"Index size: {stats['index_size_mb']} MB")

Advanced Usage

Custom KB Queries

from src.orchestrator.tools.sdk_mcp_kb_server import search_knowledge_base

# Search with filters
results = await search_knowledge_base(
    query="authentication patterns",
    top_k=10,
    filters={
        "domain": "security",
        "file_extension": ".md",
        "min_score": 0.8
    }
)

# Process results
for result in results:
    if result['score'] > 0.9:
        print(f"High relevance: {result['file']}")

GitHub Workflow

from src.orchestrator.tools.sdk_mcp_github_server import (
    create_pull_request,
    add_comment,
    create_review
)

# Create PR
pr = await create_pull_request(
    repo="owner/repo",
    title="Add authentication",
    body="Implements JWT auth with tests",
    head="feature/auth",
    base="main"
)

# Add implementation comment
await add_comment(
    repo="owner/repo",
    issue_number=pr['number'],
    body="✅ Implementation complete. Ready for review."
)

# Add code review
await create_review(
    repo="owner/repo",
    pr_number=pr['number'],
    event="APPROVE",
    body="LGTM! All quality gates passed."
)

Memory Patterns

from src.orchestrator.tools.sdk_mcp_memory_server import (
    store_memory,
    retrieve_memory,
    list_memory
)

# Store project decisions
await store_memory(
    key="architecture_decisions",
    value={
        "auth": "JWT with refresh tokens",
        "database": "PostgreSQL with SQLAlchemy",
        "caching": "Redis with TTL"
    },
    scope="project"
)

# Store session context
await store_memory(
    key="current_task",
    value="Implementing authentication",
    scope="session"
)

# Retrieve all project memory
memory = await list_memory(scope="project")
for key, value in memory.items():
    print(f"{key}: {value}")

Performance Comparison

SDK MCP vs stdio MCP

Operation stdio MCP SDK MCP Speedup
KB search (1 query) 850ms 8ms 106x
GitHub API call 450ms 45ms 10x
Memory store 120ms 2ms 60x
Session overhead 680ms 45ms 15x

Why SDK MCP is faster:

  • ✅ No subprocess spawning
  • ✅ No JSON serialization
  • ✅ No stdio communication
  • ✅ Direct Python imports
  • ✅ Shared memory space

Token Efficiency

SDK MCP reduces token usage through:

  • Prompt caching - 90% cache hit rate
  • Compressed responses - Only essential data
  • Batch operations - Multiple queries in one call

Troubleshooting

KB Server Connection Failed

Error: Failed to load knowledge base

Solution: Verify KB directory:

ls -la kb_store/faiss_metadata/
export NOVA_KB_DIR="kb_store/faiss_metadata"

GitHub MCP Authentication Failed

Error: GitHub API authentication failed

Solution: Set GitHub token:

export GITHUB_TOKEN="your-token-here"

Memory Store Not Persisting

Solution: Check storage directory permissions:

mkdir -p .nova/memory
chmod 755 .nova/memory

FAISS Index Loading Error

Error: Failed to load FAISS index

Solution: Reinstall FAISS:

pip install faiss-cpu --upgrade

Best Practices

1. Use KB Search for Standards

Let the orchestrator find relevant patterns:

✅ /novaai implement authentication following KB standards
❌ Manually searching for patterns

2. Batch GitHub Operations

Combine multiple operations:

# Batch operations
async with github_session():
    pr = await create_pull_request(...)
    await add_comment(...)
    await create_review(...)

3. Scope Memory Appropriately

Use Case Scope
Current task context session
Project decisions project
User preferences user

4. Cache KB Results

Cache frequently used KB results:

from functools import lru_cache

@lru_cache(maxsize=100)
async def get_auth_patterns():
    return await search_knowledge_base("authentication patterns")

5. Monitor Performance

Track MCP performance:

import time

start = time.time()
results = await search_knowledge_base("query")
elapsed = time.time() - start

print(f"KB search took {elapsed*1000:.1f}ms")

Security Considerations

KB Security

  • ✅ Read-only access to knowledge base
  • ✅ No write operations to KB
  • ✅ Sanitized queries (no injection)

GitHub Security

  • ✅ Token stored in environment variable
  • ✅ Scoped permissions (repo, read/write)
  • ✅ No token logging

Memory Security

  • ✅ Session isolation
  • ✅ Project-scoped storage
  • ✅ No cross-project access

Next Steps