Which integrations are available for this server?

Provides integration with Cloudflare R2 for cloud storage persistence of databases. Manages multi-tenant DuckDB databases with query execution, caching, and built-in UI. Supports S3-compatible storage via MinIO for database persistence.

How do I use DuckPond MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@DuckPond MCP Server query user_abc: SELECT * FROM users LIMIT 10" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

DuckPond MCP Server

by jordanburke

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Hybrid

DuckPond MCP Server

Node.js CI CodeQL

Model Context Protocol (MCP) server for multi-tenant DuckDB management with R2/S3 cloud storage.

Built on top of the duckpond library, this MCP server enables AI agents to manage per-user DuckDB databases with automatic cloud persistence.

Features

🦆 Multi-Tenant DuckDB - Isolated databases per user with LRU caching
☁️ Cloud Storage - Seamless R2/S3 integration for persistence
🔌 Dual Transport - stdio (Claude Desktop) and HTTP (server deployments)
🔐 Authentication - OAuth 2.0 and Basic Auth support for HTTP
🎯 MCP Tools - Query, execute, stats, cache management
🖥️ DuckDB UI - Built-in web UI for database inspection and debugging
📊 Type Safe - Full TypeScript with functype error handling

Related MCP server: CentralMind/Gateway

Quick Start

Installation

# Global installation
npm install -g duckpond-mcp-server

# Or use directly with npx
npx duckpond-mcp-server

Claude Desktop Setup (stdio)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "duckpond": {
      "command": "npx",
      "args": ["-y", "duckpond-mcp-server"],
      "env": {
        "DUCKPOND_R2_ACCOUNT_ID": "your-account-id",
        "DUCKPOND_R2_ACCESS_KEY_ID": "your-access-key",
        "DUCKPOND_R2_SECRET_ACCESS_KEY": "your-secret-key",
        "DUCKPOND_R2_BUCKET": "your-bucket"
      }
    }
  }
}

HTTP Server

# Start HTTP server on port 3000
npx duckpond-mcp-server --transport http

# With custom port
npx duckpond-mcp-server --transport http --port 8080

Available MCP Tools

`query`

Execute a SQL query for a specific user and return results.

Input:

{
  userId: string // User identifier
  sql: string // SQL query to execute
}

Output:

{
  rows: T[]              // Query results
  rowCount: number       // Number of rows
  executionTime: number  // Execution time in ms
}

`execute`

Execute DDL/DML statements (CREATE, INSERT, UPDATE, DELETE) without returning results.

Input:

{
  userId: string // User identifier
  sql: string // SQL statement to execute
}

Output:

{
  success: boolean
  message: string
  executionTime: number
}

`getUserStats`

Get statistics about a user's database.

Input:

{
  userId: string // User identifier
}

Output:

{
  userId: string
  attached: boolean // Is user currently cached?
  lastAccess: string // ISO 8601 timestamp
  memoryUsage: number // Bytes
  storageUsage: number // Bytes
  queryCount: number
}

`isAttached`

Check if a user's database is currently cached in memory.

Input:

{
  userId: string // User identifier
}

Output:

{
  attached: boolean
  userId: string
}

`detachUser`

Manually detach a user's database from the cache to free resources.

Input:

{
  userId: string // User identifier
}

Output:

{
  success: boolean
  message: string
}

Configuration

Environment Variables

DuckDB Settings

DUCKPOND_MEMORY_LIMIT - Memory limit (default: 4GB)
DUCKPOND_THREADS - Number of threads (default: 4)
DUCKPOND_CACHE_TYPE - Cache type: disk, memory, noop (default: disk)

Storage Configuration

By default, DuckPond stores databases locally. For cloud deployments, configure R2 or S3.

Local Storage (Default)

# Databases stored in ~/.duckpond/data by default
# Customize with:
export DUCKPOND_DATA_DIR=/path/to/data

npx duckpond-mcp-server

Cloudflare R2

export DUCKPOND_R2_ACCOUNT_ID=your-account-id
export DUCKPOND_R2_ACCESS_KEY_ID=your-access-key
export DUCKPOND_R2_SECRET_ACCESS_KEY=your-secret-key
export DUCKPOND_R2_BUCKET=your-bucket

npx duckpond-mcp-server

AWS S3

export DUCKPOND_S3_REGION=us-east-1
export DUCKPOND_S3_ACCESS_KEY_ID=your-access-key
export DUCKPOND_S3_SECRET_ACCESS_KEY=your-secret-key
export DUCKPOND_S3_BUCKET=your-bucket

npx duckpond-mcp-server

S3-Compatible (MinIO, etc.)

export DUCKPOND_S3_REGION=us-east-1
export DUCKPOND_S3_ACCESS_KEY_ID=minioadmin
export DUCKPOND_S3_SECRET_ACCESS_KEY=minioadmin
export DUCKPOND_S3_BUCKET=duckpond
export DUCKPOND_S3_ENDPOINT=http://localhost:9000

npx duckpond-mcp-server

Multi-Tenant Settings

DUCKPOND_MAX_ACTIVE_USERS - LRU cache size (default: 10)
DUCKPOND_EVICTION_TIMEOUT - Idle timeout in ms (default: 300000)
DUCKPOND_STRATEGY - Storage strategy: parquet, duckdb, hybrid (default: duckdb)
DUCKPOND_DATA_DIR - Local data directory (default: ~/.duckpond/data)

Cloudflare R2 Configuration

DUCKPOND_R2_ACCOUNT_ID - R2 account ID
DUCKPOND_R2_ACCESS_KEY_ID - R2 access key
DUCKPOND_R2_SECRET_ACCESS_KEY - R2 secret key
DUCKPOND_R2_BUCKET - R2 bucket name

AWS S3 Configuration

DUCKPOND_S3_REGION - S3 region (e.g., us-east-1)
DUCKPOND_S3_ACCESS_KEY_ID - S3 access key
DUCKPOND_S3_SECRET_ACCESS_KEY - S3 secret key
DUCKPOND_S3_BUCKET - S3 bucket name
DUCKPOND_S3_ENDPOINT - Custom S3 endpoint (for MinIO, etc.)

HTTP Transport Authentication

OAuth 2.0

export DUCKPOND_OAUTH_ENABLED=true
export DUCKPOND_OAUTH_USERNAME=admin
export DUCKPOND_OAUTH_PASSWORD=secret123
export DUCKPOND_OAUTH_USER_ID=admin-user
export DUCKPOND_OAUTH_EMAIL=admin@example.com

npx duckpond-mcp-server --transport http

OAuth Endpoints:

/oauth/authorize - Authorization endpoint (login form)
/oauth/token - Token endpoint (authorization_code & refresh_token)
/oauth/jwks - JSON Web Key Set
/oauth/register - Dynamic client registration

Features:

Authorization code flow with PKCE (S256 & plain)
Refresh token rotation
JWT access tokens (configurable expiration)

Basic Authentication

export DUCKPOND_BASIC_AUTH_USERNAME=admin
export DUCKPOND_BASIC_AUTH_PASSWORD=secret123
export DUCKPOND_BASIC_AUTH_USER_ID=admin-user
export DUCKPOND_BASIC_AUTH_EMAIL=admin@example.com

npx duckpond-mcp-server --transport http

JWT Configuration

DUCKPOND_JWT_SECRET - Secret for signing JWTs (auto-generated if not set)
DUCKPOND_JWT_EXPIRES_IN - Token expiration in seconds (default: 31536000 = 1 year)

HTTP Endpoints

MCP Protocol

POST /mcp - MCP protocol endpoint (Server-Sent Events)
- Requires: Accept: application/json, text/event-stream
- Initialize session, then call tools

Server Information

GET / - Server info and capabilities
GET /health - Health check

OAuth (when enabled)

GET /oauth/authorize - Authorization endpoint
POST /oauth/token - Token endpoint
GET /oauth/jwks - JSON Web Key Set
POST /oauth/register - Client registration

DuckDB UI

GET /ui - UI status and available users
GET /ui/:userId - Start UI for specific user (returns URL for direct access)

DuckDB UI

The MCP server includes built-in support for DuckDB UI, allowing you to visually inspect and debug your database through a web browser.

How It Works

With DUCKPOND_DEFAULT_USER set, the UI auto-starts when the server starts. Just open http://localhost:4213 in your browser.

The UI runs on port 4213 because DuckDB UI requires specific browser features (SharedArrayBuffer) that work best with direct access.

Claude Desktop Config (Recommended)

{
  "mcpServers": {
    "duckpond": {
      "command": "npx",
      "args": ["-y", "duckpond-mcp-server", "--ui"],
      "env": {
        "DUCKPOND_DEFAULT_USER": "claude",
        "DUCKPOND_DATA_DIR": "${HOME}/.duckpond/data"
      }
    }
  }
}

The UI automatically starts for the default user. Open http://localhost:4213 in your browser.

HTTP Mode

# Start server
npx duckpond-mcp-server --transport http --port 3000

# Start UI for user "claude"
curl http://localhost:3000/ui/claude

# Access UI directly
# Browser: http://localhost:4213

stdio Mode without Default User

If no DUCKPOND_DEFAULT_USER is set, a management server starts for manual user selection:

# Start with UI management server
npx duckpond-mcp-server --ui --ui-port 4000

# Start UI for a user
curl http://localhost:4000/ui/claude

# Access UI directly
# Browser: http://localhost:4213

Docker

# Using docker-compose (recommended)
docker compose up -d

# Start UI for a user
curl http://localhost:3000/ui/claude

# Access UI directly
# Browser: http://localhost:4213

# Simple docker run
docker run -p 3000:3000 -p 4213:4213 duckpond-mcp-server

# Start UI for a user, then access directly
curl http://localhost:3000/ui/claude
# Browser: http://localhost:4213

Why direct port access? DuckDB UI uses SharedArrayBuffer which requires specific CORS headers. Direct access to port 4213 ensures full compatibility with the UI's WebAssembly requirements.

UI Features

Database Explorer - Browse schemas, tables, and columns
SQL Notebooks - Execute queries with syntax highlighting
Table Summaries - Row counts, data profiles, previews
Column Explorer - Detailed column statistics and insights

Switching Users (HTTP Mode)

In HTTP mode, navigate to /ui/:differentUserId to switch between users. Only one user's UI is active at a time - switching automatically stops the previous UI and starts for the new user.

Environment Variables

DUCKPOND_DEFAULT_USER - Default user ID; when set, UI auto-starts for this user
DUCKPOND_UI_ENABLED - Enable UI (default: false, or use --ui flag)

CLI Flags

--ui - Enable DuckDB UI (auto-starts for DUCKPOND_DEFAULT_USER)
--ui-port <port> - Management server port, only used when no default user (default: 4000)
--ui-internal-port <port> - DuckDB UI port (default: 4213)

Development

Local Development

# Clone repository
git clone https://github.com/jordanburke/duckpond-mcp-server.git
cd duckpond-mcp-server

# Install dependencies
pnpm install

# Development mode (watch)
pnpm dev

# Run tests
pnpm test

# Format and lint
pnpm validate

Testing the Server

# Test stdio transport
pnpm serve:test

# Test HTTP transport
pnpm serve:test:http

# Test with OAuth
DUCKPOND_OAUTH_ENABLED=true \
DUCKPOND_OAUTH_USERNAME=admin \
DUCKPOND_OAUTH_PASSWORD=secret \
pnpm serve:test:http

# Test with Basic Auth
DUCKPOND_BASIC_AUTH_USERNAME=admin \
DUCKPOND_BASIC_AUTH_PASSWORD=secret \
pnpm serve:test:http

Development Commands

# Pre-checkin validation
pnpm validate      # format + lint + test + build

# Individual commands
pnpm format        # Format with Prettier
pnpm lint          # Fix ESLint issues
pnpm test          # Run tests
pnpm test:watch    # Run tests in watch mode
pnpm test:coverage # Run tests with coverage
pnpm build         # Production build
pnpm ts-types      # Check TypeScript types

Architecture

Library-First Design

The MCP server is a thin transport layer over the duckpond library:

┌─────────────┐     ┌──────────────┐
│ stdio Mode  │     │  HTTP Mode   │
│ (index.ts)  │     │(FastMCP/3000)│
└──────┬──────┘     └──────┬───────┘
       │                   │
       └───────┬───────────┘
               │
       ┌───────▼────────┐
       │ MCP Tool Layer │  (server-core.ts)
       │ - Error mapping│
       │ - Result format│
       └───────┬────────┘
               │
       ┌───────▼────────┐
       │    DuckPond    │  npm: duckpond@^0.1.0
       │ - Multi-tenant │
       │ - LRU Cache    │
       │ - R2/S3        │
       │ - Either<E,T>  │
       └───────┬────────┘
               │
       ┌───────▼────────┐
       │ DuckDB + Cloud │
       └────────────────┘

Key Components

src/index.ts - CLI entry point, transport selection
src/server-core.ts - DuckPond wrapper with MCP result types
src/server-stdio.ts - stdio transport for Claude Desktop
src/server-fastmcp.ts - HTTP transport with FastMCP
src/tools/index.ts - MCP tool schemas and implementations

Error Handling

Uses functype for functional error handling:

// DuckPond returns Either<Error, T>
const result = await pond.query(userId, sql)

// MCP server converts to MCPResult<T>
result.fold(
  (error) => ({ success: false, error: formatError(error) }),
  (data) => ({ success: true, data }),
)

Use Cases

Personal Analytics

Store per-user analytics data with automatic cloud backup:

// User creates their own tables
await execute({
  userId: "user123",
  sql: "CREATE TABLE orders (id INT, total DECIMAL, date DATE)",
})

// Query their data
const result = await query({
  userId: "user123",
  sql: "SELECT SUM(total) FROM orders WHERE date > '2024-01-01'",
})

Multi-User Applications

Each user gets isolated DuckDB instance
Automatic LRU eviction manages memory
Cloud storage persists user data
Fast queries with DuckDB's columnar engine

Data Science Workflows

Parquet file management
Cloud data lake integration
Complex analytical queries
Per-user sandboxed environments

Troubleshooting

Server Won't Start

Check DuckDB installation:

npm list duckdb

Verify environment variables:

printenv | grep DUCKPOND

Authentication Issues

OAuth not working:

Verify DUCKPOND_OAUTH_USERNAME and DUCKPOND_OAUTH_PASSWORD are set
Check browser console for errors
Ensure redirect URIs match

Basic Auth failing:

Verify credentials are set correctly
Check Authorization: Basic <base64> header format
Ensure username/password match environment variables

Memory Issues

Adjust memory limits:

export DUCKPOND_MEMORY_LIMIT=8GB
export DUCKPOND_MAX_ACTIVE_USERS=5

Monitor cache usage:

const stats = await getUserStats({ userId: "user123" })
console.log(`Memory: ${stats.memoryUsage} bytes`)

Storage Issues

R2/S3 connection errors:

Verify credentials are correct
Check bucket exists and is accessible
Test with AWS CLI: aws s3 ls s3://your-bucket

Parquet file issues:

Ensure DuckDB parquet extension is loaded
Check file permissions in storage bucket

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT

duckpond - Core multi-tenant DuckDB library
functype - Functional programming utilities for TypeScript
Model Context Protocol - MCP specification

Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs/

Available Tools

6 tools

detachUserA

Manually detach a user's database from the cache to free resources

ParametersJSON Schema

Name	Required	Description	Default
`userId`	No	User identifier (optional if DUCKPOND_DEFAULT_USER is set)

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry full behavioral disclosure. It mentions detaching and freeing resources, but does not detail side effects, error conditions, or required state (e.g., user must be attached).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no extraneous information, efficiently conveying the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema or annotations, the description covers the core functionality. However, it lacks details on prerequisites and error states, which slightly reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single optional parameter 'userId'. The tool description does not add additional meaning beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'detach', the resource 'user\'s database', and the outcome 'free resources'. It distinguishes from sibling tools like 'isAttached' and 'query'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for freeing resources by detaching, but does not explicitly state when to use or avoid, nor does it mention alternatives or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

executeB

Execute SQL statement (DDL/DML) for a specific user without returning results

ParametersJSON Schema

Name	Required	Description	Default
`userId`	No	User identifier (optional if DUCKPOND_DEFAULT_USER is set)
`sql`	Yes	SQL statement to execute (DDL/DML)

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only mentions that no results are returned, but crucially omits that executing DDL/DML can be destructive, requires certain permissions, may affect database state, and does not indicate error handling or side effects. This lack of transparency is a significant gap for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the core purpose and a key constraint (no results). It is front-loaded and without wasted words. However, it could be slightly restructured or bulleted for clarity, but overall it is concise and effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of output schema and annotations, the description should provide more contextual completeness. It fails to mention return value on success (e.g., affected rows), error behavior, prerequisites (e.g., user attachment), or whether the operation is idempotent. For a potentially destructive SQL execution tool, this is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters adequately. The tool description adds minimal value beyond what's in the schema—it reiterates that the SQL is DDL/DML and that userId is per user. This meets the baseline for high schema coverage but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Execute', the resource 'SQL statement (DDL/DML)', the scope 'for a specific user', and the outcome 'without returning results'. This effectively distinguishes it from sibling tools like 'query' which likely return results, and from administrative tools like 'detachUser' or 'listUsers'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings, especially 'query'. It does not mention that 'execute' is for DDL/DML operations without result sets, while 'query' is for SELECT statements that return results. There are no when-not-to-use instructions or alternatives listed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getUserStatsB

Get statistics about a user's database (memory usage, query count, etc.)

ParametersJSON Schema

Name	Required	Description	Default
`userId`	No	User identifier (optional if DUCKPOND_DEFAULT_USER is set)

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavioral traits. It only states that the tool gets statistics, but does not indicate whether it is read-only, requires authentication, has rate limits, or is destructive. The mention of 'etc.' is vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that concisely conveys the tool's purpose. There is no redundant or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no annotations, no output schema, and only one optional parameter, the description is minimally adequate. It tells the agent what the tool does, but lacks details on return format, error handling, or usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100% (the userId parameter has a description). The tool description does not add significant meaning beyond the schema, but it aligns with the parameter by mentioning 'a user's database'. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get statistics about a user's database (memory usage, query count, etc.)'. It uses a specific verb (Get) and resource (statistics about a user's database), and distinguishes it from sibling tools like detachUser, execute, and listUsers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or scenarios where this tool is appropriate, nor does it exclude cases where other tools should be used.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

isAttachedB

Check if a user's database is currently cached in memory

ParametersJSON Schema

Name	Required	Description	Default
`userId`	No	User identifier (optional if DUCKPOND_DEFAULT_USER is set)

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must bear the full burden. It indicates a read-only check (no side effects), which is appropriate. However, it does not disclose error conditions, authentication requirements, or the meaning of 'cached'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently communicates the tool's purpose. It is appropriately sized for a simple check operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks information about the return value (expected to be boolean) and error handling (e.g., if user not found or default user used). Given the simplicity, it is moderately complete but could be enhanced.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with a description for 'userId'. The tool description adds no extra context beyond what the schema already provides, so a baseline score of 3 is warranted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('check') and the resource ('user's database cached in memory'). It effectively distinguishes from sibling tools like 'detachUser' and 'execute' by implying a read-only query, though it could be more explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., 'detachUser' or 'listUsers'). The agent is left to infer usage context from the name and siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listUsersA

List all currently cached users and cache statistics

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It states 'list all currently cached users and cache statistics', which suggests a read-only operation, but it does not disclose whether there are side effects, authentication needs, rate limits, or exactly what 'cache statistics' entails. The description is adequate but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no wasted words. It is front-loaded with the core action and result. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does not elaborate on the format or content of the returned data, especially 'cache statistics'. For a simple listing tool the description is minimally adequate, but it could be more complete by specifying what statistics are included.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so schema coverage is trivially 100%. The description adds no parameter-level detail because there are none. According to guidelines, 0 parameters warrants a baseline of 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' and resource 'all currently cached users and cache statistics', clearly distinguishing from sibling tools like detachUser, execute, getUserStats, isAttached, and query. It precisely communicates the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you need a list of cached users and overall cache stats, but it does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among siblings. Only implied context is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

queryB

Execute a SQL query for a specific user and return results

ParametersJSON Schema

Name	Required	Description	Default
`userId`	No	User identifier (optional if DUCKPOND_DEFAULT_USER is set)
`sql`	Yes	SQL query to execute

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry full behavioral burden. It only states it executes and returns results, but does not disclose whether queries are read-only, destructive, or require specific permissions, which is critical for a SQL tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the verb. However, it could be expanded with more context without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of SQL execution and lack of output schema or annotations, the description is inadequate. It omits details on error handling, permission requirements, and result format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the schema already describes both parameters adequately. The description adds little beyond 'for a specific user', which is already hinted in the userId description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Execute' and the resource 'SQL query', and specifies it is for a specific user, which distinguishes it from a general SQL execution tool like 'execute'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus sibling tools like 'execute' or 'getUserStats'. The description implies user-specific queries but does not provide explicit usage context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.5.1Jun 10, 2026
- ChangeddetachUser1 field changed
  - removedInput schema / additionalProperties
```
Removed value: -false
```
- Changedexecute1 field changed
  - removedInput schema / additionalProperties
```
Removed value: -false
```
- ChangedgetUserStats1 field changed
  - removedInput schema / additionalProperties
```
Removed value: -false
```
- ChangedisAttached1 field changed
  - removedInput schema / additionalProperties
```
Removed value: -false
```
- ChangedlistUsers1 field changed
  - removedInput schema / additionalProperties
```
Removed value: -false
```
- Changedquery1 field changed
  - removedInput schema / additionalProperties
```
Removed value: -false
```
6 tool updatesv0.4.4May 26, 2026
- First observeddetachUser
- First observedexecute
- First observedgetUserStats
- First observedisAttached
- First observedlistUsers
- First observedquery

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0

Scored 2026-09-09 18:40 across 6 tools

Disambiguation4/5

query and execute both run SQL but are clearly differentiated by whether results are returned, while the remaining tools have distinct management purposes. isAttached, getUserStats, and listUsers target different aspects of user database state. Only query/execute could potentially be confused, but the descriptions resolve the boundary.

Naming Consistency2/5

Tool names mix lowercase single-word verbs like query and execute with camelCase compound names like getUserStats and detachUser. isAttached also follows a different predicate-style pattern rather than verb_noun. The naming style is inconsistent across the set.

Tool Count5/5

Six tools is a well-scoped size for this server's purpose. Each tool covers a distinct need: SQL execution, user statistics, cache status, cache eviction, and user listing. No tool feels redundant or extraneous.

Completeness4/5

The tool surface covers the core workflow of querying and executing SQL, inspecting user state, and managing cached database attachment. A manual attach tool is missing, but automatic attachment on first use likely makes it unnecessary. Overall the domain is well covered with only minor optional gaps.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Related MCP Connectors

Motecloud MemoryOAuth
io.github.motecloud
Cloud-hosted MCP server for durable AI memory
Knowledge & Memory Cloud Platforms
2
nlqdb — analytical memory for AI agents AOAuth
com.nlqdb
Analytical memory for AI agents: a real Postgres queried in plain English over MCP. One command.
Databases Knowledge & Memory Search
631
StateyOAuth
ai.statey
An agent-native database over MCP: shared, validated, structured records in every AI chat.
Databases Knowledge & Memory
2
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2

Related MCP Servers

Multi Database MCP Server
Databases Developer Tools
FreePeak
A
license
Not graded
quality
A
maintenance
The Multi DB MCP Server is a high-performance implementation of the Database Model Context Protocol designed to revolutionize how AI agents interact with databases. Currently supporting MySQL and PostgreSQL databases.
Updated 18 days ago (2026-08-24 20:59 UTC)
420
MIT
CentralMind/Gateway
Databases RAG Systems Developer Tools
centralmind
A
license
Not graded
quality
B
maintenance
MCP-Server from your Database optimized for LLMs and AI-Agents. Supports PostgreSQL, MySQL, ClickHouse, Snowflake, MSSQL, BigQuery, Oracle Database, SQLite, ElasticSearch, DuckDB
Updated a year ago (2025-07-18 16:15 UTC)
548
Apache 2.0
Legion Database MCP Server
Databases Search
fastmcp-me
A
license
Not graded
quality
D
maintenance
A unified MCP server for querying and managing multiple database types (PostgreSQL, MySQL, SQL Server, etc.) via natural language through AI assistants.
Updated 8 months ago (2026-01-20 21:47 UTC)
GPL 3.0
mnemos
Knowledge & Memory Search AI & Machine Learning
ncz-os
A
license
Not graded
quality
B
maintenance
MCP server providing persistent memory, semantic search, versioned storage, webhook fanout, and unified LLM routing for AI agents via FastAPI runtime with multiple backend options.
Updated 13 days ago (2026-08-29 15:25 UTC)
31
Apache 2.0

DuckPond MCP Server

Features

Quick Start

Installation

Claude Desktop Setup (stdio)

HTTP Server

Available MCP Tools

query

execute

getUserStats

isAttached

detachUser

Configuration

Environment Variables

DuckDB Settings

Storage Configuration

Multi-Tenant Settings

Cloudflare R2 Configuration

AWS S3 Configuration

HTTP Transport Authentication

OAuth 2.0

Basic Authentication

JWT Configuration

HTTP Endpoints

MCP Protocol

Server Information

OAuth (when enabled)

DuckDB UI

DuckDB UI

How It Works

Claude Desktop Config (Recommended)

HTTP Mode

stdio Mode without Default User

Docker

UI Features

Switching Users (HTTP Mode)

Environment Variables

CLI Flags

Development

Local Development

Testing the Server

Development Commands

Architecture

Library-First Design

Key Components

Error Handling

Use Cases

Personal Analytics

Multi-User Applications

Data Science Workflows

Troubleshooting

Server Won't Start

Authentication Issues

Memory Issues

Storage Issues

Contributing

License

Related Projects

Support

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

`query`

`execute`

`getUserStats`

`isAttached`

`detachUser`