# isaacwasserman/mcp-snowflake-server architecture

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

- Interactive diagram: https://gitdiagram.com/isaacwasserman/mcp-snowflake-server
- Repository: https://github.com/isaacwasserman/mcp-snowflake-server

## Overview

#### Purpose and Entry Point
This is a Python Model Context Protocol (MCP) server that gives MCP clients such as Claude Desktop controlled access to Snowflake SQL, metadata, and schema/insight resources. The executable server and MCP tool/resource registration are centered in `src/mcp_snowflake_server/server.py`; package entry-point metadata is expected in `pyproject.toml`.

#### Runtime and Deployment
The server runs as a local stdio MCP process, commonly launched through `uv`/`uvx`, and can also be containerized through `Dockerfile`. It targets Snowflake as its external system of record. Credentials and connection defaults can come from CLI/environment configuration or named TOML connections (`example_connections.toml`). `runtime_config.json` supplies runtime exclusion policy for database/schema/table discovery.

#### MCP Server Boundary
`src/mcp_snowflake_server/server.py` is the protocol-facing boundary. It parses operational flags such as connection selection, write enablement, logging, and tool exclusion; creates the service dependencies; then exposes MCP tools and URI resources. MCP clients never access the Snowflake connector directly.

#### Snowflake Access Layer
`src/mcp_snowflake_server/db_client.py` encapsulates Snowflake connection construction, query execution, and metadata discovery. Server handlers delegate read queries, permitted mutations/table creation, and database/schema/table/column inspection to this layer. This isolates Snowflake connector behavior, authentication modes, and result handling from MCP concerns.

#### Query Safety and Write Control
Read operations are available through the query tool path in `src/mcp_snowflake_server/server.py`. Write-capable tools are conditionally registered only when explicit write permission is enabled. `src/mcp_snowflake_server/write_detector.py` classifies or validates SQL intent, forming the key policy boundary that separates `SELECT` access from allowed `INSERT`, `UPDATE`, `DELETE`, and table-creation operations.

#### Schema Context Flow
Metadata requests flow MCP handler → database client → Snowflake → serialized tool response. When prefetching is enabled, discovered table schemas are additionally transformed into `context://table/{table_name}` resources. Filtering configured through `runtime_config.json` limits what catalog objects enter either tool results or precomputed context.

#### Insight Memo and Serialization
The server maintains an in-process, dynamically updated `memo://insights` resource; `append_insight` updates that memo and triggers resource-visible state changes in `src/mcp_snowflake_server/server.py`. `src/mcp_snowflake_server/serialization.py` provides the response boundary for converting Snowflake-native values and rows into MCP-safe structured results.

Main entry points: [`src/mcp_snowflake_server/server.py`](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py) (MCP Server), [`src/mcp_snowflake_server/db_client.py`](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/db_client.py) (Database Client), [`src/mcp_snowflake_server/serialization.py`](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/serialization.py) (Response Serialization), [`runtime_config.json`](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/runtime_config.json) (Discovery Exclusions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Server"]
  node_server["MCP Server<br/>protocol boundary<br/>[server.py]"]
  node_query_tools["Query Tools<br/>MCP tools<br/>[server.py]"]
  node_metadata_tools["Metadata Tools<br/>MCP tools<br/>[server.py]"]
  node_context_resources["Table Context Resources<br/>URI resources<br/>[server.py]"]
  node_insight_memo["Insight Memo<br/>URI resource<br/>[server.py]"]
end

subgraph group_data["Snowflake Access"]
  node_db_client["Database Client<br/>Snowflake adapter<br/>[db_client.py]"]
  node_write_detector["Write Detector<br/>SQL policy<br/>[write_detector.py]"]
  node_serializer["Response Serialization<br/>result adapter<br/>[serialization.py]"]
end

subgraph group_runtime["Runtime &amp; Deployment"]
  node_runtime_config["Discovery Exclusions<br/>runtime policy"]
  node_connections["Named Connections<br/>connection config"]
  node_packaging["Package Entry Point<br/>Python packaging<br/>[pyproject.toml]"]
  node_container["Container Image<br/>deployment"]
end

node_client(("MCP Client<br/>external client"))
node_snowflake[("Snowflake<br/>external database")]

node_client -->|"stdio MCP"| node_server
node_packaging -->|"launches"| node_server
node_container -->|"runs"| node_server
node_connections -.->|"connection defaults"| node_server
node_server -->|"registers"| node_query_tools
node_server -->|"registers"| node_metadata_tools
node_server -->|"publishes"| node_context_resources
node_server -->|"updates via append_insight"| node_insight_memo
node_query_tools -->|"validates writes"| node_write_detector
node_query_tools -->|"delegates SQL"| node_db_client
node_metadata_tools -->|"delegates discovery"| node_db_client
node_runtime_config -.->|"filters discovery"| node_db_client
node_db_client -->|"connector calls"| node_snowflake
node_db_client -->|"rows and values"| node_serializer
node_serializer -->|"structured results"| node_query_tools
node_serializer -->|"structured results"| node_metadata_tools
node_metadata_tools -->|"prefetched schemas"| node_context_resources

click node_server "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py"
click node_query_tools "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py"
click node_metadata_tools "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py"
click node_context_resources "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py"
click node_insight_memo "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py"
click node_db_client "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/db_client.py"
click node_write_detector "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/write_detector.py"
click node_serializer "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/serialization.py"
click node_runtime_config "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/runtime_config.json"
click node_connections "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/example_connections.toml"
click node_packaging "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/pyproject.toml"
click node_container "https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_query_tools,node_metadata_tools,node_context_resources,node_insight_memo toneBlue
class node_db_client,node_write_detector,node_serializer toneAmber
class node_runtime_config,node_connections,node_packaging,node_container toneMint
class node_client,node_snowflake toneNeutral
```

## Components

### MCP Server

- [MCP Server](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py): protocol boundary · Parses flags, constructs services, and registers tools and resources. · `src/mcp_snowflake_server/server.py`
- [Query Tools](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py): MCP tools · Read SQL path and conditionally registered write tools. · `src/mcp_snowflake_server/server.py`
- [Metadata Tools](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py): MCP tools · Database, schema, table, and column discovery. · `src/mcp_snowflake_server/server.py`
- [Table Context Resources](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py): URI resources · Prefetched schemas exposed as context://table/{table_name}. · `src/mcp_snowflake_server/server.py`
- [Insight Memo](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/server.py): URI resource · Dynamically updated memo://insights state. · `src/mcp_snowflake_server/server.py`

### Snowflake Access

- [Database Client](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/db_client.py): Snowflake adapter · Owns connections, execution, and catalog inspection. · `src/mcp_snowflake_server/db_client.py`
- [Write Detector](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/write_detector.py): SQL policy · Classifies SQL intent before permitted mutations or table creation. · `src/mcp_snowflake_server/write_detector.py`
- [Response Serialization](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/src/mcp_snowflake_server/serialization.py): result adapter · Converts Snowflake-native values and rows to MCP-safe results. · `src/mcp_snowflake_server/serialization.py`

### Runtime & Deployment

- [Discovery Exclusions](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/runtime_config.json): runtime policy · Limits catalog objects available to discovery and prefetch. · `runtime_config.json`
- [Named Connections](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/example_connections.toml): connection config · Optional TOML connection defaults. · `example_connections.toml`
- [Package Entry Point](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/pyproject.toml): Python packaging · Defines executable server metadata. · `pyproject.toml`
- [Container Image](https://github.com/isaacwasserman/mcp-snowflake-server/blob/main/Dockerfile): deployment · Optional containerized server runtime. · `Dockerfile`

### Other components

- **MCP Client**: external client · Claude Desktop or another MCP consumer.
- **Snowflake**: external database · System of record for SQL and metadata.

## Connections

- MCP Client → MCP Server: stdio MCP
- Package Entry Point → MCP Server: launches
- Container Image → MCP Server: runs
- Named Connections → MCP Server: connection defaults
- MCP Server → Query Tools: registers
- MCP Server → Metadata Tools: registers
- MCP Server → Table Context Resources: publishes
- MCP Server → Insight Memo: updates via append_insight
- Query Tools → Write Detector: validates writes
- Query Tools → Database Client: delegates SQL
- Metadata Tools → Database Client: delegates discovery
- Discovery Exclusions → Database Client: filters discovery
- Database Client → Snowflake: connector calls
- Database Client → Response Serialization: rows and values
- Response Serialization → Query Tools: structured results
- Response Serialization → Metadata Tools: structured results
- Metadata Tools → Table Context Resources: prefetched schemas