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"

Flag	What it does
`--token` / `DYNOXIDE_MCP_AUTH_TOKEN`	Use a fixed token instead of the persisted one. Required for any non-loopback bind.
`--host`	Bind beyond `127.0.0.1`.
`--allowed-host`	Accept an extra `Host` header by name (repeatable) - needed to reach it by hostname.
`--no-auth`	Disable auth. Loopback binds only.

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:

Category	Tools	What they do
Tables	5	Create, describe, list, update, delete tables
Items	4	Get, put, update, delete individual items
Batch	3	Batch get, batch write, bulk put (up to 10K items)
Query & Scan	2	Query with key conditions and filters, full table scans
Transactions	2	Atomic multi-item reads and writes
PartiQL	3	SQL-like queries via ExecuteStatement
TTL	3	Manage time-to-live settings and sweep expired items
Streams	4	List, describe, and read DynamoDB Streams
Snapshots	4	Point-in-time backups and rollback
Tags	3	Tag and untag resources
Info	1	Database size, table count, storage mode

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

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.

Getting Started

Usage

Reference