senior-projects-manager-mcp-server

Remote MCP server ("gateway") for triggering deployed Zoho Zia agents. The gateway itself — OAuth, HTTP client, MCP transport — is agent-independent; which agent a call reaches is resolved through the registry in src/agents.ts. It currently exposes one tool, ask_senior_projects_manager, whose default (and only currently registered) target is the deployed Zoho Zia Senior Projects Manager agent (portal damianknowles, agent id 20971000000021961), reached via its /trigger API.

Reference implementation: ~/zia-agent/zia_agent.py (interactive CLI script this server generalizes into a long-running HTTP service).

Architecture

src/agents.ts — registry of addressable Zia agents (key → display name → numeric agent id). Adding a new agent means adding an entry here, not touching the client or transport. DEFAULT_ZIA_AGENT_KEY (env ZIA_DEFAULT_AGENT, defaults to senior-projects-manager) picks the agent used when a call doesn't name one.
src/zohoZiaClient.ts — agent-independent client: Zoho OAuth token refresh/caching, and triggerZiaAgent(message, agentKey?) which resolves agentKey through the registry and POSTs to that agent's trigger URL. Has no built-in knowledge of the Senior Projects Manager specifically.
src/index.ts — MCP server/transport plumbing plus the one registered tool, which is a thin wrapper: agent param → triggerZiaAgent.

Tool

`ask_senior_projects_manager`

Field	Type	Description
`message`	string	Natural-language request, e.g. `"What should I work on next?"`
`agent`	string, optional	Registry key of the agent to address. Defaults to `senior-projects-manager`. An unrecognized key returns an error listing the known keys rather than silently falling back.

Returns the agent's plain-text response. Because the underlying agent has write access to Zoho Projects (and limited access to Mail/CRM/WorkDrive), calls that ask it to create or change records will actually do so, subject to the agent's own confirmation rules (see its instructions/guardrails in Zia Agent Studio).

Local development

npm install
cp .env.example .env   # fill in ZOHO_CLIENT_ID / ZOHO_CLIENT_SECRET / ZOHO_REFRESH_TOKEN
npm run dev

By default the server speaks streamable HTTP on POST http://localhost:3000/mcp (health check at GET /healthz). Set TRANSPORT=stdio to run it as a local stdio MCP server instead (for e.g. the Claude Desktop config).

The HTTP transport uses the MCP TypeScript SDK's current recommended stateless pattern: StreamableHTTPServerTransport with sessionIdGenerator: undefined (no session state kept between requests — each POST /mcp is fully self-contained) and a fresh McpServer per request, built via the SDK's createMcpExpressApp() helper (JSON body parsing plus optional DNS-rebinding host validation, see MCP_ALLOWED_HOSTS above).

Configuration

All configuration is via environment variables (see .env.example):

Variable	Required	Notes
`ZOHO_CLIENT_ID`	yes	Zoho self-client OAuth credentials
`ZOHO_CLIENT_SECRET`	yes
`ZOHO_REFRESH_TOKEN`	yes
`ZOHO_TOKEN_URL`	no	Defaults to `https://accounts.zoho.com/oauth/v2/token`
`ZIA_AGENT_BASE_URL`	no	Defaults to `https://ziaagents.zoho.com/ziaagents/api/v1/agents`; the gateway appends `/{agentId}/trigger` per call
`ZIA_AGENT_ORG_ID`	no	Defaults to `933376281`
`ZIA_AGENT_SESSION_ID`	no	Defaults to `10000`
`ZIA_SENIOR_PROJECTS_MANAGER_AGENT_ID`	no	Overrides the Senior Projects Manager's numeric agent id (default `20971000000021961`)
`ZIA_DEFAULT_AGENT`	no	Registry key used when a call omits `agent`. Defaults to `senior-projects-manager`
`MCP_SERVER_API_KEY`	required in production	Bearer token clients must send to `POST /mcp`. The server refuses to start with `NODE_ENV=production` and no key set.
`MCP_HTTP_HOST`	no	Selects the SDK's DNS-rebinding host-validation mode (not the actual bind address). Defaults to `0.0.0.0` (no restriction).
`MCP_ALLOWED_HOSTS`	no	Comma-separated allowed `Host` header values. Set once a deployment hostname is known to enable strict validation.
`PORT`	no	Defaults to `3000`; most PaaS providers inject this
`TRANSPORT`	no	`http` (default) or `stdio`

Access tokens are refreshed from the Zoho refresh token on demand and cached in memory until ~1 minute before expiry.

Registering another agent

To make the gateway able to address a second Zia agent (e.g. the Inbox Execution Agent), add an entry to the ZIA_AGENTS map in src/agents.ts with its key, display name, and numeric agent id — no changes needed in the client or transport layers. Callers then pass that key as the tool's agent argument; omitting it keeps using the default.

Connecting an MCP client

Once deployed, point a remote-MCP-capable client at:

https://<your-deployment-host>/mcp

with header Authorization: Bearer <MCP_SERVER_API_KEY>.

Cloud deployment

Docker

docker build -t senior-projects-manager-mcp-server .
docker run -p 3000:3000 \
  -e ZOHO_CLIENT_ID=... \
  -e ZOHO_CLIENT_SECRET=... \
  -e ZOHO_REFRESH_TOKEN=... \
  -e MCP_SERVER_API_KEY=... \
  -e NODE_ENV=production \
  senior-projects-manager-mcp-server

Render

render.yaml defines a Blueprint web service (npm install && npm run build / npm start, health check on /healthz). The four secret env vars (ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REFRESH_TOKEN, MCP_SERVER_API_KEY) are marked sync: false — set them in the Render dashboard rather than committing them.

Any other Node-friendly host (Fly.io, Railway, a plain VM, etc.) works the same way: build with npm install && npm run build, run npm start, and set the same environment variables.

Security note

This server triggers a live business agent with write access to a real Zoho Projects portal, CRM notes, and WorkDrive uploads. Do not deploy it without MCP_SERVER_API_KEY set, and treat that key like any other credential.