How DBHub Adopts the New MCP Spec 2026-07-28 - DBHub, Minimal Database MCP Server

July 28, 2026 MCP shipped its 2026-07-28 revision: the initialize handshake is gone, requests are self-contained, and the protocol becomes request/response. We adopted it alongside the TypeScript SDK v2 that implements it. The upgrade ships in DBHub 1.0.0 — 2026-07-28 clients get the new protocol on the same /mcp endpoint that keeps serving 2025-era clients. This post shows each change with before/after code, and what we evaluated but did not build.

1. The stateless core

DBHub’s HTTP transport has always been stateless — no session affinity, safe behind a round-robin load balancer. The 2025-era protocol assumed a session, so we faked statelessness: a fresh transport and server instance per request, session management disabled by hand. Before:

app.post("/mcp", async (req, res) => {
  try {
    // In stateless mode, create a new instance of transport and server for each request
    // to ensure complete isolation. A single instance would cause request ID collisions
    // when multiple clients connect concurrently.
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined, // Disable session management for stateless mode
      enableJsonResponse: true // Use JSON responses (SSE not supported in stateless mode)
    });
    const server = createServer();

    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  } catch (error) {
    console.error("Error handling request:", error);
    if (!res.headersSent) {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

After (SDK v2’s createMcpHandler — one factory, both protocol eras):

const mcpHandler = createMcpHandler(createServer, { onerror: logMcpError("handler") });
const mcpNodeHandler = toNodeHandler(mcpHandler, { onerror: logMcpError("adapter") });

app.all("/mcp", (req, res) => {
  void mcpNodeHandler(req, res, req.body);
});

On 2026-07-28, each request carries protocol version, client identity, and capabilities in _meta — no initialize exchange, no Mcp-Session-Id. The per-request model we hand-rolled is now the native serving model; 2025-era clients are handled by the SDK’s built-in stateless fallback. stdio got the same treatment: server.connect(new StdioServerTransport()) became serveStdio(createServer). Result: ~25 lines of session-faking deleted. Running N replicas behind any load balancer is now spec-guaranteed instead of workaround-dependent.

2. Cacheable `tools/list`

DBHub’s tool list is fixed per configuration, yet every 2025-era client re-fetches it each session — the protocol had no way to say “this doesn’t change.” The 2026-07-28 revision adds ttlMs / cacheScope fields on cacheable results. Our entire change: Before:

const server = new McpServer({
  name: SERVER_NAME,
  version: SERVER_VERSION,
});

After:

const server = new McpServer(
  { name: SERVER_NAME, version: SERVER_VERSION },
  {
    cacheHints: {
      "tools/list": { ttlMs: TOOLS_LIST_CACHE_TTL_MS, cacheScope: "private" },
    },
  }
);

On the wire:

{
  "result": {
    "tools": [ { "name": "execute_sql", ... }, { "name": "search_objects", ... } ],
    "ttlMs": 300000,
    "cacheScope": "private"
  }
}

Result: clients skip re-fetching the tool list for five minutes at a time. Not “forever” because DBHub hot-reloads its TOML config and the tool list can change at runtime — the TTL bounds staleness.

3. Header-based routing

2026-07-28 clients send Mcp-Method and Mcp-Name headers on every Streamable HTTP request, so a gateway in front of DBHub can tell a write-capable execute_sql call from a search_objects call without parsing JSON bodies. Our change was one CORS line (the headers come from the SDK): Before:

res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');

After:

res.header('Access-Control-Allow-Headers',
  'Content-Type, Mcp-Session-Id, MCP-Protocol-Version, Mcp-Method, Mcp-Name');

Result: an nginx front can throttle tool execution with no MCP awareness:

# Throttle tool execution; leave schema exploration unthrottled
map $http_mcp_name $mcp_write_limit {
    "execute_sql"  $binary_remote_addr;
    default        "";
}
limit_req_zone $mcp_write_limit zone=mcp_writes:10m rate=10r/m;

4. Evaluated and skipped: MRTR write confirmation

Multi-round-trip requests (MRTR) replace server-initiated elicitation: a tool returns resultType: "input_required" and the client retries with answers — which finally works over stateless HTTP. The obvious application for a database tool: a confirmation prompt before writes. We designed it and didn’t ship it:

Confirmation is the host’s job. DBHub already annotates write-capable tools with destructiveHint: true, and hosts like Claude Code gate destructive calls behind their own approval UI. A server-side prompt double-confirms.
The fallback is weak. Clients without elicitation degrade to a confirm: true argument, which models learn to set preemptively.
It required new config. Every design added TOML knobs on top of the existing readonly boolean, creating conflicting semantics.

The evaluation did trigger a cleanup that needed no new config. Read-only enforcement used to re-interpret the readonly boolean in four places. It now flows through one pipeline: every statement is classified (read | dml | ddl | admin | unknown, dialect-aware), and the config compiles into a class→verdict policy. Before (one of four scattered interpretations):

const isReadonly = toolConfig?.readonly === true;
if (isReadonly && !areAllStatementsReadOnly(sql, connector.id)) {
  return createToolErrorResponse(errorMessage, "READONLY_VIOLATION");
}

After (all four sites consume one policy):

const policy = policyFromReadonly(toolConfig?.readonly);
if (sqlVerdict(policy, sql, connector.id) === "deny") {
  return createToolErrorResponse(errorMessage, "READONLY_VIOLATION");
}

The verdict set can grow a confirm member later — when elicitation-capable clients are the norm, MRTR write confirmation slots into the two gate sites without touching config. Until then, readonly = true/false remains the entire configuration vocabulary.

5. Compatibility

2025-era clients are unaffected. Same /mcp endpoint, same initialize handshake, served by the SDK’s stateless fallback. stdio clients see no difference.
One caveat for hand-rolled HTTP clients: the legacy path now answers with spec-standard SSE framing (event: message / data: {...}) instead of plain JSON bodies. MCP clients already accept both; a raw curl script needs to read the data: line.
No config migration. No TOML key is added or changed.

Takeaway

For DBHub, adoption was mostly deletion — the spec absorbed our workaround — plus two small opt-ins (cache hints, CORS headers). Everything here ships in DBHub 1.0.0. The source is at github.com/bytebase/dbhub; the adoption is a readable series of commits on main.

​1. The stateless core

​2. Cacheable tools/list

​3. Header-based routing

​4. Evaluated and skipped: MRTR write confirmation

​5. Compatibility

​Takeaway