# joshuarileydev/supabase-mcp-server architecture

> Architecture diagram of the GitHub repository joshuarileydev/supabase-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joshuarileydev/supabase-mcp-server
- Repository: https://github.com/joshuarileydev/supabase-mcp-server

## Overview

##### Main Components

a) Client Layer
- AI Models (Claude)
- Other MCP Clients

b) MCP Server Layer (Core)
- Request Handler
- Protocol Adapter
- Authentication Manager (for SUPABASE_API_KEY)

c) Service Layer
- Project Management Service
- Organization Management Service

d) External Integration Layer
- Supabase Management API
- This as an external service at the bottom

##### Component Relationships

- Clients → MCP Server (HTTP/WebSocket)
- MCP Server → Service Layer (Internal calls)
- Service Layer → Supabase Management API (HTTP)

##### Specific Implementation Details

- Blue rectangles for core MCP server components
- Green rectangles for service layer components
- Gray rectangles for external systems
- Yellow rectangles for authentication/security components

##### Technical Stack Elements to Highlight

- TypeScript Runtime (based on .ts files)
- Schema Validation (indicated by schemas.ts)
- NPX Distribution Method
- Environment Configuration

##### Architectural Patterns to Emphasize

- Protocol Adapter Pattern (MCP implementation)
- Service Layer Pattern
- External Gateway Pattern (Supabase API integration)

**[External Clients (AI/Other)]**
- ↓
**[Authentication Manager]**
- ↓
**[MCP Protocol Adapter]**
- ↓
**[Request Handler]**
- ↙         ↘
**[Project     [Organization**
**Service]      Service]**
- ↘         ↙
**[Supabase Management API]**

Important Considerations:

##### Clear separation between
- Client interface layer
- Core MCP processing
- Service implementation
- External API integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef external fill:#gray,stroke:#333
    classDef core fill:#blue,stroke:#333
    classDef service fill:#green,stroke:#333
    classDef auth fill:#yellow,stroke:#333
    
    %% Legend
    subgraph Legend
        L1[Internal Component]:::core
        L2[Service Component]:::service
        L3[External System]:::external
        L4[Auth Component]:::auth
    end

    %% External Clients Layer
    subgraph Clients
        Claude[Claude AI Model]:::external
        OtherMCP[Other MCP Clients]:::external
    end

    %% MCP Server Layer
    subgraph "MCP Server Core"
        AuthMgr[Authentication Manager]:::auth
        Protocol[Protocol Adapter]:::core
        ReqHandler[Request Handler]:::core
    end

    %% Service Layer
    subgraph "Service Layer"
        ProjectSvc[Project Management Service]:::service
        OrgSvc[Organization Management Service]:::service
    end

    %% External Integration
    SupabaseAPI[Supabase Management API]:::external

    %% Connections
    Claude --> AuthMgr
    OtherMCP --> AuthMgr
    AuthMgr --> Protocol
    Protocol --> ReqHandler
    ReqHandler --> ProjectSvc
    ReqHandler --> OrgSvc
    ProjectSvc --> SupabaseAPI
    OrgSvc --> SupabaseAPI

    %% Click Events
    click ReqHandler "https://github.com/JoshuaRileyDev/supabase-mcp-server/blob/main/index.ts"
    click Protocol "https://github.com/JoshuaRileyDev/supabase-mcp-server/blob/main/index.ts"
    click ProjectSvc "https://github.com/JoshuaRileyDev/supabase-mcp-server/blob/main/dist/index.js"
    click OrgSvc "https://github.com/JoshuaRileyDev/supabase-mcp-server/blob/main/dist/index.js"
    click AuthMgr "https://github.com/JoshuaRileyDev/supabase-mcp-server/blob/main/schemas.ts"
```
