DynamoDB MCP for Codex

Codex can read your DynamoDB schema and query
your tables once you give it a MCP server to call. Codex configures MCP in
TOML, not JSON, and that difference is where most setups die — the table name is
mcp_servers, snake_case, and it is not the mcpServers key every other client uses.

This guide covers the config, the transport rule, the timeouts worth setting, and how to
connect without putting AWS credentials in the agent's environment. For how the options
compare, see the DynamoDB MCP server overview.

What Codex can do once it's connected

• Read your real schema — tables, key schema, indexes, and the attributes that actually appear in items.
• Run queries — Query, Scan, GetItem and PartiQL against live data, so it can verify its own assumptions.
• Aggregate — counts and group-bys DynamoDB can't do natively.
• Propose edits — into a reviewable staging area, not into your table.

Before you start

1. Install DynoTable — download it and add the AWS profile Codex should see.
2. Turn the MCP server on — Settings → MCP Server. Off by default, bound to 127.0.0.1.
3. Expose a profile — its MCP section → Expose via MCP. The connection is hard-bound to that profile's credentials and region.

Copy the endpoint and real port from that pane.

Add the server to config.toml

Codex reads MCP servers from ~/.codex/config.toml:

[mcp_servers.dynotable-prod]
url = "http://127.0.0.1:<port>/mcp?profile=prod"

That's the whole entry. Three details decide whether it works:

The table is mcp_servers — snake_case. Not mcpServers. Codex silently ignores a
table it doesn't recognize, so a camelCase key produces no error and no server. If your
config looks right and Codex sees nothing, check this first.

url selects the transport. Codex picks the transport from which key is present:
command means stdio, url means streamable HTTP. They are mutually exclusive — url,
bearer_token_env_var and http_headers cannot sit in a table that also has command.
DynoTable is HTTP, so url only.

?profile=prod is a hint, not authorization. It pre-selects the profile in
DynoTable's approval prompt; you still approve the connection in the app.

Optional knobs worth setting

[mcp_servers.dynotable-prod]
url = "http://127.0.0.1:<port>/mcp?profile=prod"
startup_timeout_sec = 30
tool_timeout_sec = 60
enabled = true

tool_timeout_sec is the one that matters for DynamoDB. A Scan over a large table can
outlast a short default and surface as a tool error rather than as the slow query it
actually is. If Codex reports timeouts on big tables, raise this before assuming the
connection is broken.

enabled = false is a clean way to park a server without deleting the block.

Project-scoped config

Codex also reads .codex/config.toml from a project directory, for trusted projects.
Don't put a loopback server there if the repo is shared — the port is per-machine and
your teammates don't run DynoTable. Keep this one in ~/.codex/config.toml.

Approve the connection

On first connect, DynoTable shows a consent prompt naming the client and asking for a
scope:

• Read only — schema, queries, item reads. No changes.
• Read & stage — plus staging changes for you to review. Never a direct write.
• Full access — plus opening views, filters and exports. Writes still go through staging.

Start at Read only. Scope is re-checked on every call, so narrowing takes effect
immediately.

Verify it actually loaded

Restart Codex after editing config.toml — it reads the file at startup, so an edit
mid-session changes nothing. Then ask for something only your data answers: "list the
tables in this profile and their key schemas."

A hedged, generic answer means the tools never loaded. Work the checklist below.

Tip

Codex has a long-standing class of reports where servers defined in config.toml don't
load. In practice it's nearly always one of three things: the mcpServers camelCase
typo, an edit that was never followed by a restart, or a url key sitting in a table
that also has command. Check all three before going further.

Why not give Codex AWS credentials?

The standard pattern — an MCP server holding an AWS access key and secret — hands the
agent's process the full IAM power of those keys, with no DynamoDB-specific review step.

The risk isn't a malicious model. It's that an MCP tool result is untrusted input: a
row, a document or a fetched page can carry instructions. That's
prompt injection, and against a write-capable server holding your
keys it acts on your tables directly.

Warning

Never give an autonomous agent both your AWS credentials and a direct write path to a
production table. Keep it read-only, or put a human commit step in between.

Through DynoTable:

• Your AWS credentials never reach the agent. DynoTable holds the profiles and makes the calls; nothing in the Codex process can read a key.
• There is no direct write tool. Not gated — absent. At Read & stage the worst outcome is a diff card you review.

Troubleshooting

Codex doesn't see the server at all. In order: is the table named mcp_servers
(snake_case), did you restart Codex after editing, and is the TOML valid?

Server defined but not starting. Check for a command key in the same table as
url — they're mutually exclusive. Also confirm enabled isn't false.

Connects, then times out on queries. Raise tool_timeout_sec. A large Scan is slow,
not broken.

Connected, zero tools. No profile exposed in DynoTable, or the connection was
approved at a scope exposing nothing you asked for.

Edits didn't change DynamoDB. Expected — they're staged. Commit them from the
staging area.

FAQ

How do I connect Codex to DynamoDB?

Install DynoTable, turn on its MCP server under Settings → MCP Server, expose the AWS
profile you want Codex to see, then add an [mcp_servers.dynotable] table to
~/.codex/config.toml with a url pointing at the endpoint from that pane. Restart
Codex and approve the connection in DynoTable at the scope you want.

Where does Codex configure MCP servers?

In ~/.codex/config.toml, using one TOML table per server named
[mcp_servers.dynotable]. Codex also reads .codex/config.toml from a trusted project
directory, but a loopback server belongs in the home-directory file because the port is
per-machine.

Why doesn't Codex see my MCP server in config.toml?

The most common cause is the table name: it must be mcp_servers in snake_case, not
mcpServers. Codex ignores an unrecognized table without an error. The next two causes
are editing the file without restarting Codex, and putting a url key in a table that
also has command.

Does Codex use url or command for a remote MCP server?

Use url for a streamable HTTP server like DynoTable. Codex selects the transport from
which key is present — command means stdio, url means HTTP — and the two cannot
appear in the same table.

Can Codex write to my DynamoDB tables?

Not directly, through DynoTable — there is no commit tool to call. At Read & stage or
Full access the agent stages a change, it appears as a reviewable diff in the app, and it
is written only when you commit it. A community MCP server holding write-capable AWS keys
can write directly.

Related

• DynamoDB MCP server: the options compared — DynoTable vs AWS's official server vs the community ones.
• Same setup for Claude Code and Cursor.
• MCP server docs — full setup, scopes, consent and the security model.
• Staging — how proposed writes are reviewed and committed.
• DynamoDB Expression Builder — generate the KeyConditionExpression / FilterExpression in your browser, no agent involved.

Product names are trademarks of their respective owners; referenced for identification
only. Codex config format verified 2026-07-27.