MCP Server Reference

CSharpDB includes a Model Context Protocol (MCP) server that lets AI assistants — Claude Desktop, OpenAI Desktop, Cursor, VS Code Copilot, and others — interact with a CSharpDB database through a standardized tool interface.

The server exposes 14 tools for schema inspection, data browsing, row mutations, and arbitrary SQL execution.

Running the Server

# Default direct client target (ConnectionStrings:CSharpDB or csharpdb.db)
dotnet run --project src/CSharpDB.Mcp

# Direct client target via database path
dotnet run --project src/CSharpDB.Mcp -- --database mydata.db

# Explicit endpoint selection
dotnet run --project src/CSharpDB.Mcp -- --endpoint http://localhost:61818 --transport http

Client Target Configuration

The MCP server resolves CSharpDbClientOptions in this order:

Direct remains the default transport. If you pass an HTTP endpoint without --transport, the client infers Http. Http and Grpc are implemented; named pipes remain the only additional transport option and are not implemented yet.

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "csharpdb": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/src/CSharpDB.Mcp", "--", "--database", "/path/to/mydata.db"]
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "csharpdb": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/src/CSharpDB.Mcp", "--", "--database", "/path/to/mydata.db"]
    }
  }
}

Cursor / VS Code

Add to your MCP settings (typically .cursor/mcp.json or VS Code settings):

{
  "mcpServers": {
    "csharpdb": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/src/CSharpDB.Mcp", "--", "--database", "/path/to/mydata.db"]
    }
  }
}

OpenAI Codex CLI

Add to your Codex config (~/.codex/config.toml globally, or .codex/config.toml per-project):

[mcp_servers.csharpdb]
command = "dotnet"
args = ["run", "--project", "/path/to/src/CSharpDB.Mcp", "--", "--database", "/path/to/mydata.db"]

ChatGPT Desktop

ChatGPT Desktop currently only supports remote MCP servers over HTTPS — it cannot spawn local stdio processes. To connect CSharpDB:

1. Run the MCP server with an HTTP-to-stdio bridge such as supergateway or mcp-proxy:

   npx supergateway --port 8080 -- dotnet run --project /path/to/src/CSharpDB.Mcp -- --database /path/to/mydata.db

2. Expose the local port via ngrok or similar:

   ngrok http 8080

3. In ChatGPT, go to Settings > Connectors > Create and paste the public HTTPS URL.

LM Studio

LM Studio supports MCP servers starting from v0.3.17. Open the Program tab in the right-hand sidebar, click Install > Edit mcp.json, and add CSharpDB:

{
  "mcpServers": {
    "csharpdb": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/src/CSharpDB.Mcp", "--", "--database", "/path/to/mydata.db"]
    }
  }
}

The mcp.json file lives at:

Available Tools

Schema Tools

Data Tools

Mutation Tools

The valuesJson parameter accepts a JSON object string with column names as keys:

{"name": "Alice", "age": 30, "email": "alice@example.com"}

Values are automatically coerced to CSharpDB types: integers become INTEGER, decimals become REAL, strings become TEXT, null stays NULL.

DescribeTable and BrowseTable include isIdentity metadata for identity columns.

SQL Tool

This is the general-purpose tool for anything not covered by the specialized tools — DDL (CREATE TABLE, ALTER TABLE, DROP), complex queries with JOINs and aggregates, CREATE INDEX, CREATE VIEW, CREATE TRIGGER, and so on.

Example Conversations

Once connected, an AI assistant can interact with CSharpDB naturally:

User: What tables are in the database?

Assistant: (calls ListTables) The database has 7 tables: customers, categories, products, orders, order_items, reviews, and shipping_addresses.

User: Show me the top 5 customers by order total.

Assistant: (calls ExecuteSql with a JOIN + GROUP BY query) Here are the top 5 customers...

User: Add a new product called "Widget Pro" priced at $29.99 in category 2.

Assistant: (calls InsertRow) Done — inserted 1 row into the products table.

Architecture

The MCP server is a .NET console app using stdio transport:

AI Client (Claude, Cursor, etc.)
    |
    |  stdio (JSON-RPC)
    |
CSharpDB.Mcp (Generic Host)
    |
ICSharpDbClient
    |
CSharpDB.Client (transport-selecting SDK)
    |
CSharpDB Engine (B+tree, WAL, Pager)
    |
mydata.db

All 14 tools are thin wrappers around ICSharpDbClient. In the current repo, MCP uses the direct engine-backed client by default, but the host can also be pointed at an HTTP endpoint through the same client options. The MCP SDK (ModelContextProtocol NuGet package) handles protocol framing, tool discovery, and stdio transport.

See Also

• Getting Started Tutorial — Learn the CSharpDB API step by step
• REST API Reference — HTTP endpoints for the same operations
• CLI Reference — Interactive REPL for manual exploration