Skip to content

About

Zentria MCP server — public team API for AI assistants via Model Context Protocol

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

@vitrion/zentria-mcp

npm version License: MIT Node.js Version MCP

Zentria MCP server — full Zentria public team API coverage for AI assistants via the Model Context Protocol.

Published as @vitrion/zentria-mcp.

This server uses the official public REST API at /api/public. Paths and request bodies match the OpenAPI docs; they are not invented.

Features

  • 309 tools covering nearly everything the Zentria app does: discovery, to-dos, sales, customers, campaigns and connections, invoices, CRM leads, submissions, calls and lead values, Speed to Lead, Google Business Profiles, webhooks, members, team settings and exports. The hosted connector only lists the tools that fit the scopes of the token
  • Team-bound Personal Access Token auth (Authorization: Bearer)
  • Automatic rate-limit retry (429 + Retry-After)
  • Stdio transport (Cursor, Claude Desktop, Claude Code)
  • Hosted Streamable HTTP mode with OAuth, used for the Claude custom connector at https://app.zentria.nl/mcp
  • Logs only to stderr (stdio-safe)

Requirements

  • Node.js >= 20
  • A Zentria team API key (Teams → API keys) with the scopes you need

Environment variables

Variable Required Description
ZENTRIA_API_KEY Yes Team Personal Access Token
ZENTRIA_BASE_URL No Zentria origin (default https://app.zentria.nl). Do not append /api/public.

The client also sends Accept: application/json and User-Agent: @vitrion/zentria-mcp/<version>. The API key is never written to logs.

Install

npx -y @vitrion/zentria-mcp

Cursor

Add to your user config (~/.cursor/mcp.json) or project config (.cursor/mcp.json):

{
  "mcpServers": {
    "zentria": {
      "command": "npx",
      "args": ["-y", "@vitrion/zentria-mcp"],
      "env": {
        "ZENTRIA_API_KEY": "<team-pat>",
        "ZENTRIA_BASE_URL": "https://app.zentria.nl"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Use the same mcpServers block as Cursor.

Claude Code

claude mcp add zentria -- npx -y @vitrion/zentria-mcp

Set ZENTRIA_API_KEY in your shell environment or MCP host config.

Claude custom connector (hosted)

Zentria hosts this server at https://app.zentria.nl/mcp. In Claude (web, Desktop, mobile) choose Settings → Connectors → Add custom connector, enter that URL and sign in with your Zentria account. On the consent screen you pick the team and the scopes. No API key is needed.

Running the HTTP mode

ZENTRIA_MCP_TRANSPORT=http node dist/index.js
# or
node dist/index.js --http
Variable Default Description
ZENTRIA_BASE_URL https://app.zentria.nl Zentria origin the tools call
ZENTRIA_MCP_RESOURCE_URL <ZENTRIA_BASE_URL>/mcp Public MCP URL, exactly as entered in Claude. Its path is the route served
ZENTRIA_MCP_HOST 127.0.0.1 Listen address
ZENTRIA_MCP_PORT 3333 (or PORT) Listen port

How it works:

  • The server is a pure OAuth resource server. Zentria (Laravel Passport) is the authorization server and publishes /.well-known/oauth-protected-resource/mcp, /.well-known/oauth-authorization-server and dynamic client registration at /oauth/register.
  • Requests without a valid bearer token get 401 with WWW-Authenticate: Bearer resource_metadata="…", which starts the client's sign-in.
  • Tokens are verified with GET /api/public/me (cached for 30 seconds) and forwarded unchanged to the public API. Team API keys work as bearer tokens too.
  • Each request runs on a fresh stateless server instance. GET /healthz answers {"ok":true}.

Run it behind a TLS proxy that forwards the MCP path unchanged, for example nginx:

location = /mcp {
    proxy_pass http://127.0.0.1:3333;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

For AI agents

  • Call get-me first to learn the bound team, enabled modules, and token scopes.
  • For "how is customer X doing?" call get-campaign-status (one campaign) or get-customer-status (all campaigns of a customer): leads and goals this month, the latest leads, Search Console and GA4 against the previous period, Business Profile results, grid scores with trend, reviews and open invoices in one call.
  • API keys are bound to one team — you cannot switch teams with headers.
  • Use the narrowest scopes when minting keys (sales:read, sales:write, etc.).
  • Public API docs: /api/public/docs
  • PAT writes can emit webhooks — avoid update loops on the same event.

Tool groups

352 tools. They cover what you can do in the Zentria app, limited by the rights of the member behind the key and by the scopes of the key. In the hosted connector (HTTP mode) only the tools that fit the scopes of the token are listed, so a read-only connection sees about 135 tools.

Group Examples
Discovery get-me, list-teams, get-team, list-tenants, get-tenant
To-dos list-todos, create-todo, get-todo, update-todo, delete-todo
Sales list-deals, create-deal, move-deal-stage, delete-deal, list-people, list-notes, create-deal-note, list-activities, complete-activity, list-pipelines, create-pipeline, create-pipeline-stage, list-forms, publish-form, get-sales-settings (scopes sales:read, sales:write, sales:delete, sales-admin:write)
Customers list-customers, create-customer, update-customer, delete-customer, archive-customer, restore-customer, list-customer-labels, merge-customers, invite-customer-portal-user, get-customer-mollie, create-customer-mandate-checkout
Campaigns and connections list-campaigns, create-campaign, split-campaign, set-campaign-lead-value-categories, create-elementor-connection, create-mailbox-connection, set-campaign-voys, set-campaign-phone-lines, list-crm-voys-connections, list-crm-tentelecom-connections (passwords and API keys are write-only)
Invoices list-invoices, get-invoice, get-invoice-pdf-link (a 15-minute download link for the official Mollie PDF), mark-invoice-ready, cancel-invoice, mark-invoice-paid, collect-invoice, pause-invoice-reminders (scopes invoices:read, invoices:write)
CRM leads list-crm-leads (filters on review status, date, customer, campaign, source, lead value category, invoiced and extra check), get-crm-lead (lead value in cents with category label, billing period, invoice and AI summary), approve-crm-lead, reject-crm-lead, set-crm-lead-value, confirm-crm-lead-rejection, delete-crm-lead, get-crm-workbench, list-crm-callbacks
CRM submissions and calls list-crm-submissions, mark-crm-submission-as-real, mark-crm-submission-as-spam, retry-crm-submission-processing, list-crm-calls, get-crm-call
Lead values and rules list-crm-lead-value-categories, create-crm-lead-value-category, get-crm-lead-value-settings, update-crm-lead-value-settings, backfill-crm-lead-values, list-crm-learning-rules, list-crm-ai-rule-proposals, get-crm-dashboard, get-crm-customer-report
Speed to Lead list-stl-flows, create-stl-flows-batch, list-stl-sms-templates, list-stl-leads, send-stl-flow-test-sms
Business Profiles list-business-profile-locations, update-business-profile-location, list-business-profile-reviews, create-business-profile-review-reply, create-business-profile-post, create-business-profile-post-schedule, list-business-profile-photos, list-business-profile-accounts, create-business-profile-reply-profile (scopes business-profiles:read, business-profiles:write, business-profiles-admin:write)
CommuniQate (WhatsApp) communiqate-get-connection, communiqate-list-channels, communiqate-list-templates, communiqate-create-template, communiqate-search-contacts, communiqate-list-conversations, communiqate-list-messages, communiqate-start-conversation, communiqate-send-message, communiqate-send-template, communiqate-upload-file (only when the team connected CommuniQate in Zentria; scopes communiqate:read, communiqate:write, communiqate-admin:write)
Status and Google data get-campaign-status, get-customer-status (each section is available or says why not: missing_scope, no_permission, module_off), get-campaign-google-data (Search Console, GA4 and Business Profile results of a campaign), get-business-profile-grid, list-business-profile-grid-runs, get-business-profile-grid-run (positions per point with the previous position and top 3), start-business-profile-grid-run (paid DataForSEO searches within the team budget, source search (Google Search on mobile, default, top 15, twice the price of maps; depth 10 costs the same as maps) or maps, mode live in about 20 seconds or the cheaper standard in a few minutes), list-business-profile-service-pushes, get-sales-attribution-report (deals per ad campaign, ad set or ad and the funnel steps they reached)
Mail mail-list-accounts, mail-get-account, mail-send (sends a real email from the team's own address, or via Zentria when the team has no own mail account; pass idempotencyKey so a retry never sends twice), mail-get-message, mail-list-messages (scopes mail:read, mail:write)
Webhooks list-webhooks, create-webhook (secret returned once), get-webhook-options
Members and team list-members, invite-member, change-member-role, remove-member, list-invitations, resend-invitation, cancel-invitation, list-roles, update-team, get-settings, update-team-setting, list-exports, start-export, delete-export, get-integrations

Development

git clone https://github.com/vitrionbv/zentria-mcp.git
cd zentria-mcp
npm install
npm run build
npm test
npm run dev

Inspector

npm run build
npm run inspector

Publishing

Releases go to npm with trusted publishing (OIDC). Push a v* tag to run .github/workflows/npm-publish.yml. The workflow uses id-token: write and does not use NODE_AUTH_TOKEN.

Configure the trusted publisher on npm: GitHub org vitrionbv, repo zentria-mcp, workflow npm-publish.yml.

License

MIT — see LICENSE.

Links

About

Zentria MCP server — public team API for AI assistants via Model Context Protocol

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages