DataMCP Agent connects a private PostgreSQL database to DataMCP without opening inbound network access.
The agent runs inside your network, connects outbound to DataMCP Cloud over WebSocket, and executes database operations requested through your DataMCP MCP link.
Install the agent with npm, npx, or Homebrew. Create a Local Agent connection in the dashboard before running it; the dashboard supplies the connection ID and a one-time agent token.
DATAMCP_AGENT_TOKEN="$YOUR_DATAMCP_AGENT_TOKEN" npx @datamcp/agent ro \
"$DATABASE_URL" --connection-id "$DATAMCP_CONNECTION_ID"npm install -g @datamcp/agent
DATAMCP_AGENT_TOKEN="$YOUR_DATAMCP_AGENT_TOKEN" datamcp-agent ro \
"$DATABASE_URL" --connection-id "$DATAMCP_CONNECTION_ID"Homebrew uses the same official npm package under the hood:
brew tap datamcpapp/tap
brew install datamcp-agentHomebrew 7 may ask you to trust a third-party formula first. Trust only this formula with brew trust --formula datamcpapp/tap/datamcp-agent, then run the install command again.
Build an image from the published npm package; no repository checkout or GitHub authentication is required:
docker build -t datamcp-agent:latest - <<'DOCKERFILE'
FROM node:22-alpine
RUN npm install -g @datamcp/agent@latest
USER node
ENTRYPOINT ["datamcp-agent"]
DOCKERFILE
docker run --rm --network host --env-file .env.agent datamcp-agent:latestOn Linux, --network host lets the container reach a database bound to 127.0.0.1. On Docker Desktop, omit --network host and use host.docker.internal in DATAMCP_DB_URL.
Use this for a dashboard-created connection:
DATAMCP_AGENT_TOKEN="$YOUR_DATAMCP_AGENT_TOKEN" datamcp-agent \
ro "$DATABASE_URL" \
--connection-id "$DATAMCP_CONNECTION_ID"The dashboard generates the complete command. ro is a local read-only ceiling; use a read-only PostgreSQL role as well. For writes, omit ro, set DATAMCP_READ_ONLY=false, use a narrowly privileged PostgreSQL role, and select a read-write or full-access MCP link. All three layers must permit the operation.
The anonymous, account-free flow is not supported end to end yet. Create a Local Agent connection in the dashboard first.
CLI flags win over environment variables.
For a dashboard-created tunnel, the database URL, connection ID, and one-time agent token are required. ro or DATAMCP_READ_ONLY=true is recommended for read-only access. All other settings below are optional; you can omit them and use the defaults.
| Flag | Env | Status | Description |
|---|---|---|---|
--db or ro <url> |
DATAMCP_DB_URL |
Required | PostgreSQL URL. Stays local to the agent. ro also applies a local read-only ceiling. |
--agent-token |
DATAMCP_AGENT_TOKEN |
Required | Connection-scoped token shown once during Local Agent setup. |
--api-key |
DATAMCP_API_KEY |
Legacy only | Account API key for older tunnel connections. |
--connection-id |
DATAMCP_CONNECTION_ID |
Required | DataMCP connection ID. |
ro |
DATAMCP_READ_ONLY=true |
Recommended | Local read-only ceiling. Enabled in the Docker and Kubernetes examples. |
--agent-name |
AGENT_NAME |
Optional | Cosmetic display name; defaults to the machine hostname. It does not affect access or routing. |
--log-level |
LOG_LEVEL |
Optional | debug, info, warn, or error; defaults to info. |
--port |
PORT |
Optional | Local health-check port; defaults to 3000. Do not expose it publicly. |
curl http://localhost:3000/health
curl http://localhost:3000/ready/health confirms the local process is alive.
/ready confirms the agent is connected to DataMCP Cloud.
- Database credentials stay on the machine running the agent.
- The cloud sends SQL requests over an outbound WebSocket; it does not receive the DB URL.
- The database user should still be least-privilege. Read-only MCP links should use a read-only DB role.
roprevents write requests from the cloud, but is not a substitute for database privileges. - Do not paste agent tokens, API keys, claim tokens, or database URLs into logs or support tickets.
- The dashboard's generated command uses
ro. For stronger isolation, use a database role with only the SQL privileges the workflow needs. - A write can have an unknown outcome if the agent or network fails near
COMMIT. Check the database before retrying. Replay protection is in memory and does not provide exactly-once execution across agent restarts.
- Update the version in
package.jsonandpackage-lock.json. The CLI reads it frompackage.json. - Run:
./scripts/release-check.sh- Create a Git tag:
git tag "v$(node -p 'require("./package.json").version')"
git push origin "v$(node -p 'require("./package.json").version')"-
GitHub Actions publishes:
- npm package:
@datamcp/agent - Docker image:
ghcr.io/datamcpapp/agent(currently private to the organization; use the npm-based Docker build above for public installs)
- npm package:
-
The Homebrew tap checks npm
latestevery six hours and updates its formula automatically. Run itsUpdate agent formulaworkflow manually to make a new release available immediately.
MIT