netsapiens-mcp
phoneware/netsapiens-mcp
Netsapiens MCP Server for NetSapiens Platform Integration
Instalação
npx convez-ai phoneware/netsapiens-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
NetSapiens MCP Server
🚀 Hosted, multi-user MCP for NetSapiens Any AI agent — Claude, ChatGPT, anything that speaks MCP — logs in as a real NetSapiens user, drives the full v1 + v2 API, and stays connected indefinitely. Credentials never touch the model.
⚡ Features
- 🔐 Hosted OAuth proxy — The server is the OAuth 2.1 authorization server. The user signs in on a browser page hosted here, not in the chat. NetSapiens credentials never enter the model's context.
- 🛡️ MFA built into the flow — Real NetSapiens accounts have a second factor. When the upstream returns an MFA challenge, the user gets a passcode page; the bearer that reaches the AI carries the verified session.
- 🔁 Transparent NetSapiens refresh — Upstream access tokens are refreshed silently before they expire. AI sessions stay alive across long conversations.
- 🍪 Stateless login state — OAuth pending state and MFA challenges ride in HMAC-signed
HttpOnlycookies. Cloud Run instance switches mid-login don't break anything. - 🗄️ Firestore persistence — Issued tokens and dynamic client registrations survive deploys, scaling events, and instance churn. No one gets logged out on a release.
- 🤝 Claude and ChatGPT support — Public-client dynamic registration (
token_endpoint_auth_method=none, PKCE only) means ChatGPT connects out of the box alongside confidential clients like Claude. - 🧬 727 auto-generated tools from the specs — v2 OpenAPI (481) + v1 apidoc (274), regenerated on every build. When NetSapiens ships a new endpoint, drop in the new spec and rebuild.
- 🎯 Curated catalog by default (~39 task-shaped tools) — Find-this, do-that composites scaled to a model's working memory. Set
MCP_TOOL_MODE=fullto restore the full 727-tool listing. - 🧵 Multi-call workflows —
diagnose_call,user_profile,queue_health,agent_dashboard,switch_queue,find_and_call,recent_activity_for_number,voicemail_inbox_summary,schedule_forwarding. Each replaces 2–5 round-trips with one shaped response. - 🔍 API discovery escape hatch — When the catalog doesn't cover it, the model uses
search_apito find a tool by keyword across the full 727, then invokes it by name withcall_api. Same filters apply. - 🚫 Security stripped at generation time — Token, JWT, API-key, certificate, and credential endpoints are excluded from the registry at build time. The model can't mint or revoke credentials because there's no tool to do it.
- 👥 Scope-aware role filtering — A Basic User sees ~25 self-service tools; an Office Manager / Reseller / Super User sees the full ~39 plus administrative operations. NetSapiens still enforces server-side.
- 🪛 Operator-tunable — Disable globs (
MCP_DISABLED_TOOLS=delete_*,remove_*), action blocks (MCP_DISABLED_ACTIONS), semantic destructive toggle (MCP_DISABLE_DESTRUCTIVE=true— blocks any tool that mutates irreversibly, including composites likeend_call), in-band confirmation prompt (MCP_CONFIRM_DESTRUCTIVE=true— the model has to get the user's blessing in the AI client before any destructive call), branded login page (MCP_LOGIN_HEADER,MCP_ICON_URL). No code change for per-deployment policy. - 🧠 Per-user tool promotion — Generated tools the user reaches for repeatedly via
call_apiget promoted into their personal default tool list automatically. Per NetSapiens user, persisted to Firestore, threshold-based, all filters still apply. The serversendToolListChangednotification fires once on the call that crosses the threshold. - 🧪 A real test suite — 230 passing, including a draft-2020-12 JSON Schema guard that compiles every tool's input schema on every test run, so a bad spec can't silently break the connector.
- 🚀 Auto-deploy from
main— Cloud Build runs the suite, builds the image, pushes it to Artifact Registry, and rolls out a new Cloud Run revision. Env vars carry over; CI ships code, ops sets config.
📋 What this server is
- Two MCP transports.
stdiofor local CLI integrations andhttp(Streamable HTTP) for hosted deployments. Production useshttp. - Auto-generated tools. 481 tools from the NetSapiens v2 OpenAPI spec plus 274 from the v1 apidoc dump, all regenerated on every build from
spec/netsapiens-api-v2.jsonandspec/netsapiens-api-v1.json. - Hosted OAuth login. The server acts as its own OAuth authorization server. The user enters NetSapiens credentials in a login page served by this MCP server — credentials never pass through the AI. MFA is supported.
- Transparent token refresh. Upstream NetSapiens tokens are refreshed silently when they expire; AI clients see continuous sessions.
- Stateless flow state. OAuth pending state and MFA challenges ride in HMAC-signed cookies, so logins survive container restarts and Cloud Run instance switches.
- Firestore persistence. MCP tokens and DCR client registrations live in Firestore when
MCP_PERSISTENCE=firestore(recommended on Cloud Run) so reconnects survive deploys. - Public-client DCR. Honors
token_endpoint_auth_method=nonefor clients like ChatGPT that authenticate via PKCE only. - Tool gating. Read/write annotations on every tool, plus glob-based disable patterns (
MCP_DISABLED_TOOLS) and action-level disables (MCP_DISABLED_ACTIONS).
🏗️ Architecture
AI client (Claude/ChatGPT)
│ OAuth 2.1 DCR + browser login
▼
[ MCP HTTP server (this repo) ] ← OAuth proxy, login page, MFA, cookies
│ bearer token + PKCE
▼
[ NetSapiens API (v1 + v2) ]
Per-user upstream NetSapiens tokens are stored alongside our MCP-issued tokens. Every tool call attaches the right upstream bearer; tools never see credentials.
💻 Running locally (stdio)
npm install
npm run build
export NETSAPIENS_API_URL=https://edge.example.com
export NETSAPIENS_API_TOKEN=<your-token> # OR set OAuth username/password
npm start # MCP_TRANSPORT defaults to stdio
Add this entry to your local MCP client config (Claude Desktop, etc.):
{
"mcpServers": {
"netsapiens": {
"command": "node",
"args": ["/path/to/netsapiens-mcp/build/index.js"]
}
}
}
🌐 Running as a hosted server (HTTP)
export MCP_TRANSPORT=http
export MCP_PORT=3000
export MCP_BASE_URL=https://mcp.example.com
export NETSAPIENS_API_URL=https://edge.example.com
export NETSAPIENS_OAUTH_CLIENT_ID=<operator-client-id>
export NETSAPIENS_OAUTH_CLIENT_SECRET=<operator-client-secret>
export MCP_SESSION_SECRET=<32+ random hex> # signs login-state cookies
npm start
Connect from Claude / ChatGPT by giving it the URL https://mcp.example.com/mcp. The client will DCR-register, redirect the user to /authorize, the user signs in, and the bearer flows back to the AI automatically.
☁️ Cloud Run deployment
This repo ships with a Cloud Run-friendly Dockerfile and a cloudbuild.yaml. The minimum production stack:
| Component | Purpose |
|---|---|
| Cloud Run service | Runs the HTTP server with session affinity and min-instances=1 |
| Global Load Balancer + static IP | Stable A record target if you want to point DNS at an IP instead of ghs.googlehosted.com |
| Managed SSL cert | Auto-provisioned for the custom domain |
| Firestore (native mode) | Persistent token store and DCR client registry |
Cloud Run service account → roles/datastore.user | Firestore access |
Build, push, deploy:
gcloud builds submit --config cloudbuild.yaml --project=<your-project>
Required env vars on Cloud Run:
| Var | Notes |
|---|---|
MCP_TRANSPORT=http | enable the HTTP transport |
MCP_BASE_URL | public URL, e.g. https://mcp.example.com |
NETSAPIENS_API_URL | upstream NS API, e.g. https://edge.example.com |
NETSAPIENS_OAUTH_CLIENT_ID / _SECRET | NDP-provisioned client used for the password grant |
MCP_SESSION_SECRET | 32+ char random; signs cookies & must be stable across instances |
MCP_PERSISTENCE=firestore | enable Firestore-backed tokens and clients |
GOOGLE_CLOUD_PROJECT | Firestore project ID (auto-set on Cloud Run) |
Optional:
| Var | Notes |
|---|---|
MCP_LOGIN_HEADER | login page heading text (defaults to "NetSapiens MCP — Sign In") |
MCP_ICON_URL | URL to a square PNG; used for /favicon.* and as the logo above the login form |
MCP_LOGIN_LOGO_URL | override for just the login-form logo |
MCP_DISABLED_TOOLS | comma-separated globs to hide tools (e.g. delete_*,remove_*,*token*) |
MCP_DISABLED_ACTIONS | comma-separated action arg values to block on manage_* tools |
MCP_CORS_ORIGIN | CORS origin for the MCP transport (defaults to *) |
🔐 OAuth flow (detailed)
- AI client hits
GET /.well-known/oauth-protected-resource/mcpand/.well-known/oauth-authorization-serverfor discovery. - AI client POSTs
/register(RFC 7591 DCR). Public clients passtoken_endpoint_auth_method=noneand get back aclient_idonly; confidential clients getclient_id+client_secret. Registrations persist in Firestore. - AI redirects the user's browser to
/authorize?...with PKCE parameters. The server stores the pending request in a signed cookie (mcp_pending_auth, 15 min TTL) and renders the login page. - User submits credentials → server hits
POST {NS}/ns-api/v2/tokens(password grant). If NS responds withmfa_type/mfa_vendor, the server stores the partial state inmcp_mfa_challengeand prompts for a passcode. - On success, the server issues an authorization code and redirects back to the AI client. Cookies are cleared.
- AI exchanges the code at
/tokenfor our MCP-issued bearer + refresh token. The upstream NS token is stored alongside. - On every
/mcprequest, the server verifies the bearer, transparently refreshes the upstream NS token if it's within 60s of expiry, and forwards the request through the right NS handler.
🧰 Tools
The server exposes a curated catalog of ~39 task-shaped tools by default instead of the full 727-operation generated registry. With 700+ tools in the listing, even capable AI models stall on tool selection and burn context on enumeration; a focused default surface fixes that without losing reach.
The catalog has three layers:
- Thin composites (~28) — one-or-two-call wrappers over common NS endpoints:
find_user,find_contact,find_domain,find_phone_number,find_device,recent_calls,active_calls,call_details,call_trace,place_call,transfer_call,end_call,my_voicemails,read_voicemail,forward_voicemail,list_message_sessions,read_messages,send_message,list_queues,queue_status,agent_login,agent_logout,agent_status,my_devices,my_answer_rules,update_my_answer_rule,call_statistics,agent_statistics. - Workflow tools (9) — multi-call composites that chain endpoints to deliver a higher-level intent in one shot:
diagnose_call,user_profile,queue_health,agent_dashboard,switch_queue,find_and_call,recent_activity_for_number,voicemail_inbox_summary,schedule_forwarding. - API discovery / escape hatch (2) —
search_apiandcall_api(see next section).
The catalog is scope-aware: a basic NS user sees ~25 self-service tools; a domain admin or above sees the full ~39 including supervisory and diagnostic operations. The catalog lives in src/tools/curated/catalog.ts and src/tools/curated/workflows.ts; edit there and rebuild.
Set MCP_TOOL_MODE=full to expose the entire 727-tool generated registry instead (legacy behavior).
Every tool (curated, workflow, or generated) carries:
annotations.readOnlyHint—truefor GETs/lookups,falsefor mutations.annotations.destructiveHint—truefor delete-style operations.
API discovery: how the model reaches the long tail
The curated catalog is intentionally small. When the model needs something not in it — read an audit log, list certificates, configure a specific dial-policy rule — it discovers and calls into the full 727-operation registry via two meta-tools:
-
search_api(query, limit?)— keyword search across every generated tool's name and description. Returns ranked matches (token hits weighted, tool-name hits weighted higher). Use case: "I need to find the right tool." Example:{ "query": "auditlog", "limit": 5 }returns matches like
get_auditlog, with short descriptions. -
call_api(tool_name, args)— invoke any tool the registry knows about by exact name, with arbitrary args:{ "tool_name": "get_auditlog", "args": { "limit": 50 } }
The discovery flow:
- Model has a goal not covered by the curated catalog.
- Model calls
search_api({ query })to find candidates. - Model picks the best match (using its name + description).
- Model calls
call_api({ tool_name, args })to execute it.
This means the model browses the API the way a developer browses docs: search, read, call. The curated set handles the everyday work without an enumeration step; the meta-tools handle everything else without flooding the tool list.
All filters apply identically through call_api: MCP_DISABLED_TOOLS, MCP_DISABLED_ACTIONS, role-tier filtering. A user trying to call_api into get_accesslog (system-admin tier) gets the same "higher access tier required" rejection they'd get from the catalog. Security stripping happens at generation time — auth/token/JWT/API-key/cert/firebase endpoints are not in the registry to find, so search_api will never surface them and call_api will never invoke them. The escape hatch can't reach what isn't there.
Infra/security endpoints are stripped at generation
Auth and credential endpoints are excluded at generation time — they never enter the registry — because exposing them as AI tools is a security risk (the server handles auth itself; these would let the model mint/read/revoke tokens, keys, certs, or service-account creds). The generators drop:
- v2 tags:
Authentication/Access Token (Oauth),Authentication/API Key,Authentication/JWT,Firebase,SSL Certificates, plus the/email/verify/{token}flow. - v1 objects:
sfu(mints media-server access tokens);oauth2/tokenendpoints are inherently skipped (noobject=param).
This removes 27 v2 + 1 v1 operations (755 → 727). To change the exclusion list, edit EXCLUDED_TAGS/EXCLUDED_PATH_RE in scripts/generate-tools.ts and EXCLUDED_OBJECTS in scripts/generate-v1-tools.ts, then npm run generate.
Recommended disable patterns
For operational (non-security) trimming per deployment, MCP_DISABLED_TOOLS still applies on top. Common choice:
delete_*,remove_*
delete_*,remove_*— destructive operations you may not want an AI performing
v1 vs v2
v1_* names are RPC-style (?object=X&action=Y) v2 names are REST. Many v2 endpoints have a v1 counterpart. If the v2 coverage is sufficient for your deployment, hide all of v1 with MCP_DISABLED_TOOLS=...,v1_*.
Role-tier filtering
NetSapiens authorization is scope-tier (Super User > Reseller > Office Manager > Basic User) plus domain/territory ownership, enforced server-side with a 403 — there is no per-endpoint capability introspection endpoint to query up front. The user's scope is the only access signal available at connection time, and we read it at login.
On top of NS's own enforcement, the server hides clearly-privileged resource families from lower tiers as a UX nicety so the AI doesn't see tools it can't use:
- system_admin only: certificates, templates, images, routes, connections, firebase, backup/restore, access/audit logs, system configuration, system-wide dial policy, SFU, insight.
- reseller minimum: reseller management, domain create/delete/billing.
- everything else: visible to all authenticated users; NS enforces ownership.
The map is intentionally small and conservative — only families we're confident require a tier are gated, so a tool a user could legitimately call is never hidden. NS remains the real gatekeeper for the long tail. Disable the behavior entirely with MCP_DISABLE_ROLE_FILTER=true (then everything is visible and NS does all enforcement via 403).
🛡️ Destructive-action confirmation (elicitation gate)
Set MCP_CONFIRM_DESTRUCTIVE=true to make the server pause before any destructive tool runs and ask the user to confirm in-band, using the MCP elicitation/create capability. The user sees a "Confirm end_call on call_id=XYZ? Yes/No" prompt directly in their AI client; only on accept does the call execute. Decline or cancel and the model gets a clear "user declined" error to relay back.
MCP_DISABLE_DESTRUCTIVE wins over confirmation: if a tool is disabled outright, we don't waste the user's time prompting for a call we'd reject.
Client capability: The MCP spec requires the client to advertise capabilities.elicitation. Claude supports it; ChatGPT support is uncertain and should be verified per-deployment. If the connected client doesn't support elicitation, fail-closed is the default (the destructive call is refused with a clear error). Set MCP_CONFIRM_FALLBACK=allow to instead bypass the confirmation on incapable clients (operator opt-in only — defeats the purpose for those sessions).
🧠 Per-user tool promotion
When a user reaches for a generated tool repeatedly through call_api, the server learns and promotes it into the user's default tool list automatically. Next time the user connects, the tool is right there in the listing — no search-and-call dance.
Mechanics:
- Tracked per NetSapiens username (from the authenticated bearer), not per AI client. Use the same NS account across Claude and ChatGPT and your promotions follow you.
- Stored in the Firestore collection
mcp_tool_usagewhenMCP_PERSISTENCE=firestore(default on Cloud Run); in-memory otherwise. - Promotion fires when count ≥
MCP_PROMOTE_THRESHOLD(default3) within the lastMCP_PROMOTE_WINDOW_DAYS(default14) days. - Demotion is automatic. Once a tool's most recent call falls outside the window it drops back out of the user's catalog without any explicit action. The list is always a reflection of recent activity, not a permanent inheritance.
- Dynamic list refresh. After every successful tool call, the server diffs the user's live promoted set against a per-session snapshot. If anything changed — a fresh promotion crossed the threshold, or a previously-promoted tool just decayed — it fires
notifications/tools/list_changedonce, so AI clients re-list mid-session without reconnecting. When nothing changed, no notification is sent and the model isn't disturbed. - Promotion never bypasses other filters: a tool hidden by
MCP_DISABLED_TOOLS, role tier,MCP_DISABLE_DESTRUCTIVE, or the generation-time security strip stays hidden, no matter how many times it gets called. - Opt out per deployment with
MCP_DISABLE_PROMOTION=true.
Privacy note: This stores per-user tool-name counts and timestamps in Firestore. No arguments, no responses, no PII — just {username, toolName, count, lastUsed} rows. Worth mentioning in a deployment's user docs so it's not a surprise.
🎨 Customizing the login page
Set MCP_LOGIN_HEADER for the heading text and MCP_ICON_URL for the logo:
gcloud run services update netsapiens-mcp \
--update-env-vars="MCP_LOGIN_HEADER=Login to Acme,MCP_ICON_URL=https://your-cdn/logo.png"
The same icon is served at /favicon.ico and /favicon.png so AI clients pick it up for their connector list. The favicon route fetches and caches the image bytes — it doesn't redirect, because some MCP clients won't follow redirects for favicons.
🔄 Regenerating tools
The specs are vendored at spec/netsapiens-api-v2.json (OpenAPI 3.1) and spec/netsapiens-api-v1.json (apidoc dump). To regenerate after a spec update:
npm run generate # runs both generators, writes src/generated/
npm run build # tsc compiles the generated code
prebuild runs generate automatically, so npm run build is enough most of the time.
📊 Health and observability
GET /health— uptime, active sessions, NS API URL, version.- Structured JSON logs to stderr (use
LOG_LEVEL=debugfor verbose). - Each MCP request logs through Cloud Run's standard
httpRequestschema; auth events log tojsonPayload.message.
📁 Repo layout
spec/
netsapiens-api-v2.json # OpenAPI 3.1 — 481 ops
netsapiens-api-v1.json # apidoc dump — 277 ops
scripts/
generate-tools.ts # v2 generator
generate-v1-tools.ts # v1 generator
src/
index.ts # entry point (stdio or http)
http-server.ts # Express app + MCP transport + auth wiring
netsapiens-client.ts # axios-based NS client with v1Call/request adapters
auth/
netsapiens-auth-provider.ts # OAuth provider, MFA, signed cookies
token-store.ts # file-backed store + TokenStoreLike interface
firestore-token-store.ts # Firestore-backed store
firestore-clients-store.ts # Firestore-backed DCR registry
roles.ts # NS scope → MCP user role mapping
tools/
index.ts # registry wrapper: annotations, disables, dispatch
generated/
registry.ts # generated v2 registry
tools/*.ts # 82 generated v2 tool modules
v1/
registry.ts # generated v1 registry
tools/*.ts # 61 generated v1 tool modules
types.ts # ToolDefinition + GenericApiClient
📜 License
MIT