MCP Authenticated Server

A production-ready, fork-friendly Go template for building authenticated MCP (Model Context Protocol) servers backed by a relational database.

Provides authentication, database access, vector search, SQL querying, guardrails, health checks, configuration, container orchestration, and MCP protocol handling out of the box. Fork authors add domain logic (new tools, tables, eval entries) without touching framework code.

Key Features

• AWS Cognito JWT authentication with JWKS caching and singleflight refresh
• Dual database engine support — PostgreSQL (with pgvector) and MS SQL Server
• Vector/semantic search — parallel KNN + full-text retrieval with RRF merge
• SQL query mode — read-only SQL execution with keyword blocking
• Document ingestion — structure-aware markdown chunking with idempotency
• Two-level guardrails — topic relevance gating and match score filtering
• HyDE query expansion — optional hypothetical document embeddings via Claude API
• Cross-encoder reranking — optional reranking via HTTP endpoint
• Container-first — Podman-preferred, Docker-compatible deployment
• Evaluation framework — LLM-as-judge RAG quality measurement

Architecture

See docs/DESIGN.md for the full architecture, package dependency DAG, data model, and extension points.

graph TB
    Clients["MCP Clients<br/>(Claude, agents, etc.)"]

    subgraph Server["mcp-server (Go binary)"]
        Auth["Auth Middleware<br/>(Cognito JWT)"]
        MCP["MCP Handler<br/>(Streamable HTTP)"]
        Tools["Tool Registry"]
        SearchTool["search_documents"]
        QueryTool["query_data"]
        IngestTool["ingest_documents"]
        ForkTools["(fork-added tools)"]

        subgraph Pipeline["Search Pipeline"]
            HyDE["HyDE<br/>Query Expansion"]
            Embed["Embed Client<br/>(/v1/embeddings)"]
            Guard["Guardrails<br/>L1: Topic Gate<br/>L2: Score Gate"]
            KNN["KNN Vector Search"]
            FTS["Full-Text Search"]
            RRF["RRF Merge"]
            Rerank["Reranker<br/>(optional)"]
        end

        DAL["Database Abstraction Layer"]
    end

    Cognito["AWS Cognito<br/>(JWKS)"]
    Anthropic["Anthropic API<br/>(Claude)"]
    EmbedServer["Embed Server<br/>(llama-server)"]
    RerankerServer["Reranker Server<br/>(cross-encoder)"]
    PG["PostgreSQL<br/>+ pgvector"]
    MSSQL["MS SQL Server"]

    Clients -- "HTTPS / JSON-RPC<br/>(POST /mcp)" --> Auth
    Auth --> MCP
    Auth -. "validate JWT" .-> Cognito
    MCP --> Tools
    Tools --> SearchTool
    Tools --> QueryTool
    Tools --> IngestTool
    Tools --> ForkTools

    SearchTool --> HyDE
    HyDE -. "generate hypothesis" .-> Anthropic
    HyDE --> Embed
    Embed -. "/v1/embeddings" .-> EmbedServer
    Embed --> Guard
    Guard --> KNN
    Guard --> FTS
    KNN --> RRF
    FTS --> RRF
    RRF --> Rerank
    Rerank -. "/rerank" .-> RerankerServer

    DAL --> PG
    DAL --> MSSQL
    KNN --> DAL
    FTS --> DAL
    QueryTool --> DAL
    IngestTool --> DAL

Request Sequence

A typical search_documents call showing the MCP protocol handshake and search pipeline:

sequenceDiagram
    participant C as MCP Client
    participant S as mcp-server
    participant Co as AWS Cognito
    participant A as Anthropic API
    participant E as Embed Server
    participant DB as PostgreSQL
    participant R as Reranker

    Note over C,S: Session Initialization
    C->>S: POST /mcp (initialize)
    S->>C: capabilities + Mcp-Session-Id
    C->>S: POST /mcp (notifications/initialized)

    Note over C,S: Tool Call
    C->>S: POST /mcp (tools/call: search_documents)
    S->>Co: Validate JWT (cached JWKS)
    Co-->>S: Token valid

    Note over S: Search Pipeline
    S->>A: HyDE: generate hypothesis (optional)
    A-->>S: Hypothetical passage
    S->>E: POST /v1/embeddings
    E-->>S: Query embedding vector

    Note over S: L1 Guardrail: topic relevance c

... [View full README on GitHub](https://github.com/emergingrobotics/mcp-authenticated-server#readme)