MCP Server

Dynoxide includes a built-in MCP (Model Context Protocol) server with 34 tools. Your coding agent can create tables, query data, manage snapshots, and more - all without leaving the conversation.

Setup for Claude Code

Add this to your MCP configuration:

{
  "mcpServers": {
    "dynoxide": {
      "command": "dynoxide",
      "args": ["mcp", "--db-path", "dev.db"]
    }
  }
}

The agent now has full DynamoDB access through Dynoxide.

Setup for Cursor

Same config format. Add it to your Cursor MCP settings with the dynoxide mcp command.

Streamable HTTP transport

If you prefer HTTP over stdio:

dynoxide mcp --http --port 19280

As of v0.10.0 the HTTP transport requires a bearer token on every request - the stdio setup above is unaffected. On a loopback bind, Dynoxide generates a token the first time you run it, saves it to a per-user config file (~/.config/dynoxide/mcp-token on Linux, ~/Library/Application Support/dynoxide/mcp-token on macOS), and prints a ready-to-paste client snippet. Later runs reuse it silently.

Point your agent at the /mcp endpoint and send the token in an Authorization header:

{
  "mcpServers": {
    "dynoxide": {
      "type": "http",
      "url": "http://127.0.0.1:19280/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Upgrading from before v0.10.0? Existing HTTP clients break until you add that Authorization header. The stdio transport needs no changes.

Binding beyond loopback

The server binds to 127.0.0.1 by default. To reach it from elsewhere - another container, say - bind a wider host and set a token explicitly. A non-loopback bind won't start without one:

dynoxide mcp --http --host 0.0.0.0 --token "$DYNOXIDE_MCP_AUTH_TOKEN"

Prefer the environment variable or the persisted file over --token - flag values leak into shell history and ps. On the serve subcommand these flags are prefixed (--mcp-host, --mcp-token, and so on) because serve already owns --host/--port for the DynamoDB server.

The transport also checks the Host and Origin headers against an allowlist, closing the DNS-rebinding and cross-origin gaps a loopback server can otherwise expose. The full threat model is in SECURITY.md.

Available tools

The 34 tools are grouped by category:

Table configuration

As of 0.12.0 the table tools accept the billing and capacity settings that HTTP and wasm could already set:

• create_table takes billing_mode, provisioned_throughput and on_demand_throughput. Before 0.12.0 it took none of them, so every table created over MCP came out PROVISIONED with default throughput regardless of what you asked for.
• update_table takes billing_mode, provisioned_throughput, table_class and on_demand_throughput. The handler previously hardcoded the first three to none, so the engine saw an empty update and a table could not be switched between PROVISIONED and PAY_PER_REQUEST over MCP at all.
• describe_table now reports billing_mode, table_class and the capacity settings for whichever mode the table is in, in its default view. They used to appear only under raw: true.

An invalid billing mode is rejected with DynamoDB's own enum validation message, on every surface rather than just over HTTP.

Safety controls

For read-only access (good for pointing at production snapshots):

dynoxide mcp --read-only --db-path prod-snapshot.db

To cap response sizes:

dynoxide mcp --max-items 100 --max-size-bytes 65536

Persistent storage and encryption work here as they do on serve, via --db-path and --encryption-key-file. The CLI reference has every flag on the subcommand.

Data model context

If you're using a single-table design with OneTable, you can pass the schema so the agent understands your entity model:

dynoxide mcp --data-model schema.json

The agent will see entity names, key templates, and GSI mappings in its instructions. This is context only - Dynoxide doesn't validate writes against the schema.

--data-model-summary-limit caps how many entities appear in that summary (20 by default; 0 suppresses it). On a large single-table design the full entity list can crowd out the rest of the agent's context, so trimming it is worth doing.