Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

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" --connection-id "$DATAMCP_CONNECTION_ID"

npm global

npm install -g @datamcp/agent
DATAMCP_AGENT_TOKEN="$YOUR_DATAMCP_AGENT_TOKEN" datamcp-agent ro \
  "$DATABASE_URL" --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" \
  --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.

Configuration

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.

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. ro prevents 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

  1. Update the version in package.json and package-lock.json. The CLI reads it from package.json.
  2. Run:
./scripts/release-check.sh
  1. Create a Git tag:
git tag "v$(node -p 'require("./package.json").version')"
git push origin "v$(node -p 'require("./package.json").version')"
  1. 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)
  2. The Homebrew tap checks npm latest every six hours and updates its formula automatically. Run its Update agent formula workflow manually to make a new release available immediately.

License

MIT

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages