Skip to main content
Glama
evtapps

Ditto MCP Server

by evtapps
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Ditto MCP Server — Secure DQL for Ditto

NPM Version MIT licensed Node >=18

Install in Cursor

📚 Table of Contents

Related MCP server: DB Analytics & Query Platform

Overview

An open‑source Model Context Protocol server that executes Ditto DQL over HTTPS with capability gating and safety checks. Designed for Cursor, Claude Code, VS Code Copilot Chat (MCP), Windsurf, Zed, and more.

Features

  • Ping health tool, execute_dql tool, and ditto://config resource

  • Statement guardrails: single statement, operation allow‑list, optional query pattern allow‑list

  • Config via env, CLI, or client config

  • Native ESM, strict TypeScript, zero runtime deps beyond MCP SDK

Requirements

  • Node.js >= 18.17

  • A Ditto app base URL, e.g. https://MY_APP.cloud.ditto.live

  • A Ditto API key with access to that app

Quick Start (Local)

npx -y ditto-mcp-server@latest

Defaults to stdio transport. Provide env vars (recommended):

export DITTO_BASE_URL="https://MY_APP.cloud.ditto.live"
export DITTO_API_KEY="YOUR_API_KEY"
export MCP_DITTO_ALLOWED="READ"   # or ALL / SELECT,INSERT,...

npx -y ditto-mcp-server@latest

Install in Clients

Below are minimal JSON snippets. See each client’s docs for full syntax and options.

Cursor

Add to ~/.cursor/mcp.json or project .cursor/mcp.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server@latest"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY",
        "MCP_DITTO_ALLOWED": "READ"
      }
    }
  }
}

Claude Code CLI

claude mcp add ditto -- npx -y ditto-mcp-server --timeout 20000

VS Code Copilot Chat (Insiders)

{
  "mcp": {
    "servers": {
      "ditto": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "ditto-mcp-server"],
        "env": {
          "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
          "DITTO_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

Windsurf

Add to Windsurf MCP config (see their docs for exact path):

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "Ditto": {
      "command": {
        "path": "npx",
        "args": ["-y", "ditto-mcp-server"]
      }
    }
  }
}

Roo Code / Cline

Add in settings under MCP servers or marketplace manual JSON:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

JetBrains AI Assistant

Settings → Tools → AI Assistant → MCP → Add → As JSON:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

LM Studio

Program → Install → Edit mcp.json:

{
  "mcpServers": {
    "Ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Warp

Settings → AI → Manage MCP servers:

{
  "Ditto": {
    "command": "npx",
    "args": ["-y", "ditto-mcp-server"],
    "start_on_launch": true
  }
}

Amazon Q Developer CLI

~/.aws/q/developer/cli/config.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"]
    }
  }
}

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "ditto": {
      "command": "npx",
      "args": ["-y", "ditto-mcp-server"]
    }
  }
}

Tools & Resources

  • ping – returns pong for connectivity check

  • execute_dql – run a parameterized DQL against Ditto

    • statement (string, required) – single statement, no trailing ;

    • args (object, optional) – named parameters

    • transactionId (number, optional) – X‑DITTO‑TXN‑ID

    • apiKey (string, optional) – override key; prefer env

    • baseUrl (string, optional) – override base URL

    • timeoutMs (number, optional, <= 60000)

  • Resource: ditto://config – redacted runtime config

Example: SELECT with named args

Tool: execute_dql
Args:
{
  "statement": "SELECT * FROM collection WHERE type = :t LIMIT 5",
  "args": { "t": "note" }
}

Returns a JSON envelope with items, queryType, warnings, and optional error.

Configuration

You can configure via env, CLI, or client configs. Env is preferred for secrets.

Environment variables:

  • DITTO_BASE_URL – e.g. https://MY_APP.cloud.ditto.live

  • DITTO_API_KEY – Ditto API key

  • MCP_DITTO_ALLOWED – READ, ALL, or a comma list like SELECT,INSERT

  • MCP_DITTO_QUERY_ALLOW_PATTERNS – comma/semicolon‑separated regex allow‑list

  • DITTO_TIMEOUT_MS – default per‑call timeout (ms)

  • DITTO_API_KEY_ENV – env var name to read API key from (default DITTO_API_KEY)

  • MCP_SERVER_NAME – server display name

  • MCP_SERVER_VERSION – overrides the reported server version (default: package.json version; fallback: 0.0.0-dev)

  • LOG_LEVEL – controls logging verbosity: debug|info|warn|error|silent (default: info)

Configuration precedence: CLI flags > environment variables. Reported version precedence: MCP_SERVER_VERSION > package.json > 0.0.0-dev.

CLI flags (subset):

ditto-mcp [transport] \
  --name <name> \
  --base-url <url> \
  --api-key-env <VAR> \
  --timeout <ms>

Transport argument defaults to stdio. This package currently exposes stdio only.

MCP Client One‑click Patterns

  • Cursor deeplink button above for instant install into ~/.cursor/mcp.json.

Security Notes

  • Prefer environment variables for secrets; avoid CLI args containing secrets

  • Allowed operation gating and optional regex allow‑list help constrain queries

  • Logs redact tokens and obvious secret patterns

Development

yarn
yarn build
node dist/index.js stdio

Linting is TypeScript‑strict by design. The prepack script builds automatically before npm publish.

Test with MCP Inspector

npx -y @modelcontextprotocol/inspector npx ditto-mcp-server

Alternative Runtimes

bunx -y ditto-mcp-server

Windows PowerShell example:

cmd /c npx -y ditto-mcp-server

Docker

Build the image:

docker build -t ditto-mcp .

Run with env vars:

docker run --rm -i \
  -e DITTO_BASE_URL="https://MY_APP.cloud.ditto.live" \
  -e DITTO_API_KEY="YOUR_API_KEY" \
  ditto-mcp

You can also configure Docker as a local MCP command in clients that support running a container for stdio transport. Example:

{
  "mcpServers": {
    "ditto": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "DITTO_BASE_URL",
        "-e",
        "DITTO_API_KEY",
        "ditto-mcp"
      ],
      "env": {
        "DITTO_BASE_URL": "https://MY_APP.cloud.ditto.live",
        "DITTO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Troubleshooting

  • If tools don’t appear, refresh/toggle the server in your client

  • Ensure DITTO_BASE_URL and DITTO_API_KEY are set

  • In Windows, provide full node and dist/index.js paths if needed

If your client has trouble auto-installing via npx, try bunx -y ditto-mcp-server.

Versioning & Changelog

See CHANGELOG.md.

License

MIT © EVT Engineering and contributors

This project is not affiliated with Ditto. “Ditto” is a respective trademark of its owner.

Available Tools

2 tools
execute_dqlDitto: Execute DQL queryC

Runs a query in Ditto using a parameterized DQL statement

ParametersJSON Schema
NameRequiredDescriptionDefault
statementYesDQL statement to execute (single statement; no trailing ';')
argsNoNamed parameters for the DQL
transactionIdNoOptional X-DITTO-TXN-ID for consistency
apiKeyNoDitto API key (prefer env over passing here)
baseUrlNoOverrides DITTO_BASE_URL for this call
timeoutMsNoPer-call timeout override (ms)

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral disclosure. 'Runs a query' implies execution but doesn't specify whether this is read-only, can modify data, requires authentication, has rate limits, or what happens on failure. The description lacks critical behavioral context that should be provided when annotations are absent.

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, efficient sentence that communicates the core purpose without unnecessary words. It's appropriately sized for a tool with comprehensive schema documentation and gets straight to the point with zero wasted text.

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?

For a query execution tool with 6 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what DQL is, what types of operations it supports, what the expected return format is, or any behavioral characteristics. The context signals indicate significant complexity that isn't addressed in the description.

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 all 6 parameters thoroughly. The description adds minimal value beyond what's in the schema - it mentions 'parameterized DQL statement' which hints at the 'args' parameter, but doesn't provide additional semantic context about parameter relationships or usage patterns.

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 ('Runs a query') and the target system ('in Ditto'), with the specific query type ('parameterized DQL statement'). It distinguishes from the only sibling 'ping' by focusing on query execution rather than connectivity testing. However, it doesn't specify what kind of queries (read vs write) or the resource being queried.

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. With only one sibling ('ping'), it doesn't explain that 'ping' is for connectivity testing while this is for data operations. There's no mention of prerequisites, error conditions, or typical use cases for DQL queries.

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

pingPingB

Health check for the Ditto MCP server

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It states this is a 'Health check' which implies a read-only, non-destructive operation, but it doesn't disclose behavioral traits like what 'health' entails (e.g., response time, status codes), whether it requires authentication, or any rate limits. The description is too vague for a tool with no annotation coverage.

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, efficient sentence that directly states the tool's purpose without any fluff. It is appropriately sized and front-loaded, making it easy to understand at a glance.

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's simplicity (0 parameters, no annotations, no output schema), the description is minimally adequate. It explains what the tool does but lacks details on behavioral aspects like return values or error conditions. For a health check tool, more context on expected outcomes would improve completeness.

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 tool has 0 parameters, and schema description coverage is 100% (though trivial since there are no parameters). The description doesn't need to add parameter semantics, so it meets the baseline of 4 for zero-parameter tools by not introducing unnecessary complexity.

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 tool's purpose as a 'Health check for the Ditto MCP server' with a specific verb ('check') and resource ('Ditto MCP server'). It distinguishes from the sibling tool 'execute_dql' by focusing on server health rather than data querying. However, it doesn't explicitly contrast with the sibling, so it's not a perfect 5.

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 doesn't mention typical use cases (e.g., verifying server availability before operations) or exclusions. The context is implied as a health check, but explicit usage instructions are missing.

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. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • Changedexecute_dql2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changedping1 field changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
  2. 2 tool updates
    • First observedexecute_dql
    • First observedping
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: execute_dql is for running database queries, while ping is a health check. There is no overlap or ambiguity between these functions.

Naming Consistency4/5

Both tools follow a verb_noun pattern (execute_dql, ping), though ping is a single word rather than a compound. The naming is consistent in style and readable, with only a minor deviation for the simpler ping.

Tool Count2/5

With only 2 tools, the server feels thin for a database query server. While execute_dql is core, the lack of additional tools for operations like schema inspection, data manipulation, or connection management suggests an incomplete surface.

Completeness2/5

For a Ditto database server, the tool surface is severely incomplete. It only provides query execution and a health check, missing essential operations such as listing tables, describing schemas, inserting/updating data, or managing transactions, which will limit agent capabilities.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • PostgreSQL MCP Server

    datdeboer
    A
    license
    Not graded
    quality
    D
    maintenance
    A production-ready MCP server that enables safe, read-only SQL SELECT queries against PostgreSQL databases with built-in security validation. It features connection pooling, automatic row limits, and structured logging to ensure secure and reliable database interactions.
    29
    ISC

  • DB Analytics & Query Platform

    SuryaNangunuri31
    F
    license
    Not graded
    quality
    D
    maintenance
    A FastAPI-based server that enables executing SQL queries, managing database connections, and retrieving analytics reports through MCP-integrated endpoints. It allows users to interact with database schemas, performance metrics, and access logs using structured queries.
    -

  • sql-explorer-mcp

    govern-agents
    A
    license
    Not graded
    quality
    F
    maintenance
    Read-only MCP server for SQL databases (SQL Server, Postgres, SQLite) with multi-server support and three-layer safety using AST validation and linting.
    MIT

  • duckdb_analytics_mcp

    pypi-ahmad
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides read-only SQL analytics on local CSV, Parquet, and JSON datasets using DuckDB, with pagination, security guardrails, and health monitoring.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/evtapps/ditto-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server