Docs

MCP setup for Codex, Claude, and custom clients.

z-gateway exposes a hosted MCP endpoint and a local bridge command that keeps client configuration clean while refreshing runtime credentials safely.

Getting started GitHub connector

Hosted MCP endpoint

Agents connect through z-gateway instead of calling GitHub or Postgres directly. The hosted endpoint is:

https://z-gateway.com/api/mcp

In normal setup, use the dashboard-generated command instead of manually placing bearer tokens in your MCP client config.

One-command setup pattern

npx -y @z-gateway/cli mcp add \
  --gateway https://z-gateway.com \
  --credential-id <credential-id> \
  --environment dev \
  --client claude-code

Replace <credential-id> with the value shown in the z-gateway dashboard. The CLI prompts for the shown-once bootstrap secret, stores only the local bridge credential, and writes the selected MCP client config.

Client variants

Client	Command
Codex	`npx -y @z-gateway/cli mcp add --gateway https://z-gateway.com --credential-id <credential-id> --environment dev --client codex`
Claude Code	`npx -y @z-gateway/cli mcp add --gateway https://z-gateway.com --credential-id <credential-id> --environment dev --client claude-code`
Claude Desktop	`npx -y @z-gateway/cli mcp add --gateway https://z-gateway.com --credential-id <credential-id> --environment dev --client claude-desktop`
Cursor	`npx -y @z-gateway/cli mcp add --gateway https://z-gateway.com --credential-id <credential-id> --environment dev --client cursor`

Status and removal

Check the local bridge profile and configured client:

npx -y @z-gateway/cli mcp status

Remove a client configuration when rotating setup:

npx -y @z-gateway/cli mcp remove

MCP clients may need to reconnect or start a new session after policy changes that alter the available tool list. The hosted endpoint currently advertises a stable tools list and does not rely on live tools-list change notifications.

Troubleshooting checklist

Symptom	Check
Client does not show z-gateway tools	Restart the MCP client after running mcp add and confirm mcp status lists the expected client config.
npm package not found or command not found	Confirm @z-gateway/cli has been published, npm is reachable, and Node.js 20+ is installed.
Invalid, expired, or already used credential	Reissue the bootstrap credential from the dashboard and run the setup command again.
GitHub or database calls fail	Confirm the connector is active, the target is assigned to the agent, and policy allows the requested action.
No tools visible	Check GitHub and Postgres connectors, agent status, selected environment, policy readiness, and plan limits.
Unexpected deny decision	Review runtime logs for the matched rule or default-deny reason, then update policy scope.