DataMCP Agent
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
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.
npx
DATAMCP_AGENT_TOKEN="$YOUR_DATAMCP_AGENT_TOKEN" npx @datamcp/agent ro \
"$DATABASE_URL" --stage qa --connection-id "$DATAMCP_CONNECTION_ID"
npm global
npm install -g @datamcp/agent
DATAMCP_AGENT_TOKEN="$YOUR_DATAMCP_AGENT_TOKEN" datamcp-agent ro \
"$DATABASE_URL" --stage qa --connection-id "$DATAMCP_CONNECTION_ID"
Homebrew
Homebrew uses the same official npm package under the hood:
brew tap datamcpapp/tap
brew install datamcp-agent
Homebrew 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.
Docker
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:latest
On 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.
Quick start
Registered tunnel
Use this for a dashboard-created connection:
DATAMCP_AGENT_TOKEN="$YOUR_DATAMCP_AGENT_TOKEN" datamcp-agent \
ro "$DATABASE_URL" \
--stage qa \
--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.
On QA, the backend requires ENABLE_AGENT_DEPLOYMENT=true and the dashboard requires NEXT_PUBLIC_ENABLE_AGENT_DEPLOYMENT=true. Keep both disabled in production until QA validation is complete.
Configuration
CLI flags win over environment variables.
Health checks
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.
Security model
- 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.
Release process
- 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.
License
MIT