TeamDynamix MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
TeamDynamix MCP Server
Version: 3.1.0 · Last updated: 2026-10-28
An MCP (Model Context Protocol) server that lets LLM agents interact with the TeamDynamix Web API — tickets, assets, configuration items (CMDB), projects, issues, people, groups, and reports.
Changelog
4.0.0 — Breaking: tool names. Every tool is renamed from
teamdynamix_*totdx_*(the prefix a client adds in front of a tool name left little room under the 64-character limit some model APIs enforce). Policy rules,TDX_ALLOW_TOOLSandTDX_DENY_TOOLSthat name a 3.x tool keep working through aliases; client-side allowlists do not. See Migrating to 4.0. Answers that were wrong or cut short: "open tickets" now filters by status class (TeamDynamix ignoresIsOpen), saved searches page on the server instead of returning one truncated window, replies are cut at record boundaries with a note saying where to continue, JSON mode puts the data in the text block as well asstructuredContent, andget_*tools show the whole record. Fewer round trips:app_id, statuses, priorities and types accept names, person arguments acceptme,fieldsreturns only the columns you need, reports page and can be cut to chosen columns, andcount_onlycan use a wider window (TEAMDYNAMIX_COUNT_WINDOW). Rate limits: one limiter per route that learns fromX-RateLimit-*headers, waits for a stated reset plus a 5 s margin, reports progress, and honours cancellation (a sent write is never aborted). Sign-in from the chat:tdx_sign_inopens the sign-in window on a local server. Install:npx teamdynamix-mcp-server init, a per-userTDX_HOME/.env, and a desktop extension bundle built for releases. New ticket filters:is_on_hold,closed_date_from/to,location_ids. A custom attribute filter was tried and dropped: TeamDynamix ignores that property.3.1.0 — Audit fixes, no tool changes. Security: the service-account token cache (
TEAMDYNAMIX_TOKEN_CACHE=file) moved from the shared temp folder to the per-user state folder (TDX_HOME/tokens, private folder, file replaced by rename), so the first run after upgrading logs in once more (you can delete the oldtdx-mcpfolder in your temp directory); a network-reachable HTTP server (HOSTnot loopback) now refuses to start unlessMCP_AUTH_TOKENis at least 24 characters. Reliability: scripts no longer exit while requests are queued behind the rate limit, expired search and record cache entries are dropped as new ones are stored, and concurrent stale reads of reference data share one background refresh. Scripts now sign in through the server's own login code, sonpm run verifyfails exactly as the server would for mismatched credentials. Smaller fixes:get_personencodes the UID, the ticket-reference resource rejects a non-numeric app ID, and HTTP logs "tools registered" once at start-up instead of on every request. The unusedarchive/folder was removed.3.0.0 — Breaking: tool names. The 11 ticket and asset reference lookups are replaced by
teamdynamix_get_ticket_referenceandteamdynamix_get_asset_reference, each taking akindslist (default surface 55 → 46 tools; 64 → 55 unrestricted). Policy rules,TDX_ALLOW_TOOLSandTDX_DENY_TOOLSthat name an old tool keep working: the name is translated to its replacement (a deny on any old name denies the new tool) and a warning names the replacement. Internals: one tool-surface module decides what is registered, prompts are only offered when the tools they use are registered, a server-lifecycle module owns start-up and late pruning for both transports, policy loading moved out ofconfig.ts, and service-account login moved behind the sameAuthorizationinterface SSO uses. See Migrating to 3.0.2.2.0 — Smaller tool surface:
TDX_TOOLSETSdomain allowlist, application-aware gating (tools for Ticketing, Asset/CI and Projects are not registered when the account has no such application; fails open),tools:explain. Repository hygiene: a hash-based sensitive-content scanner, a package allowlist and CI checks (see Contributing).2.1.0 — SSO user authentication: per-user token lifecycle, silent renewal via persistent browser session, Hermes CDP compatibility gate,
login/whoami/logoutCLI commands, realm-locked credential state.2.0.0 — Full rewrite: policy-gated tool registration, capability tiers (read/create/edit/destroy), structured caching with domain invalidation, rate limiting, cursor-based pagination,
defineToolframework.
Related MCP server: Freshservice MCP Server
Authenticate as yourself (SSO)
For local use, the server can act as you instead of a shared admin key. TeamDynamix then enforces your own roles and application access, and records you as the author of anything created.
npm install
npm run build
npm run login # opens Edge, you finish SSO + MFA, the window closes
npm run whoami # who you are, when the token expires, and whether renewal is healthy (~24h)
npm run logout # forget the token (add -- --all to also remove the login browser profile)MCP client config (credentials live in the gitignored .env at the project root — the server loads it from there even when the client starts it from another folder, so keep the client config free of identifying values):
{
"mcpServers": {
"teamdynamix": {
"command": "node",
"args": ["C:\\Github\\tdx_mcp\\dist\\index.js"]
}
}
}The .env file supplies TEAMDYNAMIX_BASE_URL, TEAMDYNAMIX_AUTH_METHOD=sso, and TEAMDYNAMIX_SSO_EXPECTED_USER. Set TDX_ENV_FILE to point at a different .env location, or add variables to the client's env block to override individual values (client-set variables always win).
Notes: TeamDynamix tokens last 24 hours and have no refresh token. After the first login, the server silently mints and validates a replacement about one hour before expiry. If SSO requires interaction or MFA, tools return SSO_ACTION_REQUIRED; run npm run login to recover. Sandbox and production keep separate state. See planning/plans/sso-user-auth.md.
States (npm run whoami): usable (renews automatically); renewal blocked (renewal hit MFA or another policy, a different user, or a rejected token; the current token keeps working until it expires, then run npm run login); needs renewal (expired, renews on next use if it can); sign-in required (nothing usable, run npm run login). A timeout or 5xx from TeamDynamix never discards your token. npm run logout always wins over a renewal already in progress.
Several clients at once (for example Claude Desktop and Claude Code on the same realm): they share one token file and take a lock around renewal, so only one browser window opens and the others pick up its result.
Upgrading from the first SSO release: if TEAMDYNAMIX_SSO_EXPECTED_USER is set, an existing saved sign-in is carried over after TeamDynamix confirms it is yours. Otherwise it is left untouched and you simply run npm run login. With TEAMDYNAMIX_MCP_DEPLOYMENT=external, logout --all cannot end the Hermes browser's SSO session; ask the Hermes operator.
External Hermes SSO (Still a work in progress)
Set TEAMDYNAMIX_MCP_DEPLOYMENT=external for one persistent Hermes workspace and one assigned user. This requires TRANSPORT=http, loopback HOST, a separate MCP_AUTH_TOKEN, TEAMDYNAMIX_SSO_EXPECTED_USER, and TEAMDYNAMIX_SSO_CDP_ENDPOINT=http://127.0.0.1:9222. The server attaches only to that configured CDP endpoint and creates an owned renewal tab; it never forwards a TeamDynamix token through MCP. Validate the sandbox with npm run test:hermes-sso -- --realm sandbox. See Hermes rollout.
Features
56 tools across nine areas (55 on a server that does not sign users in locally):
Area | Tools |
Auth |
|
Tickets | search, get, create, update, feed (get/add comment), tasks (get/create/update) |
Assets | search, get, create, update, feed (get/add comment) |
CMDB / Config Items | search, get, create, update, feed, relationships (get/add/remove), link to ticket |
Projects | search, get, create, update, feed (get/add comment) |
Issues | search, get, create, update |
People / Groups | lookup, search, get, get UID by username, search groups, get group, get/add/remove members |
Reference data | applications, accounts, locations, custom attributes, and two lookups with a |
Reports | list reports, get report data, list saved searches, run saved searches |
Maintenance: Update this table in the same PR that adds or removes a tool.
All list/search tools support pagination (limit/offset, plus an opaque
next_cursor) and a response_format of markdown (human-readable, default)
or json (structured data in structuredContent). Responses are capped at
25,000 characters with a message telling the agent how to narrow the query or
paginate.
The server also exposes MCP resources (tdx://applications,
tdx://{appId}/ticket-reference; the app ID must be a positive integer) so hosts
can pin reference data to context without a tool round trip, and prompts (triage_ticket,
weekly_ticket_report) that demonstrate the intended tool composition.
Working conversationally
These behaviors exist to keep an agent from burning turns on bookkeeping:
Default application — set
TEAMDYNAMIX_DEFAULT_APP_IDandapp_idbecomes optional everywhere. In an organization with dozens of ticketing applications this removes the "which app?" question from most conversations.Emails instead of UIDs — every person argument (
responsible_uid,requestor_uid,owning_customer_uid,project_manager_uid,notify_uids, and the*_uidssearch filters) accepts an email address and resolves it server-side against a cached lookup. Ambiguous addresses come back as an error listing the candidate UIDs, so the agent can retry in one turn.Names instead of IDs —
app_idtakes an application name ("Help Desk") as well as a number, andstatus_ids,priority_ids,type_idsand the create/edit equivalents take names ("On Hold"). A name matches exactly (ignoring case) or by a single partial match; anything else returns the valid choices, so the agent can correct itself in one turn.me— person arguments accept"me"for the signed-in user. It is only available when users sign in as themselves (SSO); a shared service account has no "me" and gets an error that says so.Open and closed —
is_openandstatus_classes(for example["on_hold"]) filter on TeamDynamix status classes, because the API ignoresIsOpenon ticket search.Only the columns you need — every search accepts
fields(["Title","StatusName"]) and returns a table of just those plus the ID. Unknown names are reported with valid examples.tdx_get_reporttakescolumns,limit,offsetandcount_only, and caches the run so paging does not execute the report again.Large results stay whole — a reply over the size limit is cut between records and says which
offsetto continue from. Saved searches page on the server, so a saved search of any size can be read in full.Self-correcting errors — when TeamDynamix rejects a create or update with a 400, the response appends the valid
status_id/type_id/priority_idvalues for that application, read from cache only (never an extra API call).Clickable records — rendered tickets include a TDNext link derived from the configured base URL, so answers can be handed straight to a person.
Honest counts — TeamDynamix search has no total-count endpoint, so a total rendered as
251+means "at least", not "exactly". Usecount_only=truefor "how many" questions andverbosity="compact"to scan many records cheaply.
Response format and payload size
A tool response is cut to fit the size limit at a record boundary, never mid-record:
markdown(default) returns a single rendered text block.jsonreturns the compact JSON as the text block (so a client that never showsstructuredContentto the model still delivers it) plus the same object asstructuredContent. SetTDX_STRUCTURED_CONTENT=textfor a client that would show both.
An outputSchema is deliberately not declared. The MCP SDK requires
structuredContent on every result once a tool declares one, which would force
markdown responses to carry the full JSON payload as well.
Install
The quickest route, with no clone:
npx -y teamdynamix-mcp-server init # asks for your URL, signs you in, offers a default app, prints client configinit writes one per-user config file, TDX_HOME/.env, next to your tokens. The server looks for its .env in this order and uses the first that exists: TDX_ENV_FILE, TDX_HOME/.env, then the project folder (a clone). Real environment variables, such as a client's env block, always win.
Prefer a double-click install? Each release has a desktop extension bundle (.mcpb) that asks for your URL, signs in with SSO and needs no Node setup of its own. Build one with npm run build && npm run pack:mcpb.
Setup
npm install
npm run buildConfiguration
Copy .env.example to .env and fill in your values:
cp .env.example .envVariable | Description |
| TeamDynamix organization root, Web API root, or complete API root. Examples: |
| Admin service account BEID (found in TDAdmin → Organization) |
| Admin service account Web Services Key |
| Standard user/service-account login (alternative to BEID) |
| Password for user login |
| Optional. Explicitly select |
| Local SSO identity binding; required for external Hermes |
| Local SSO browser channel: |
|
|
| Required loopback Chrome CDP endpoint for external Hermes |
| Milliseconds before expiry to attempt silent SSO renewal; default |
| Transient silent-renewal retries; default |
| Optional. Default application for app-scoped tools, so |
| Optional. Set exactly to |
| Optional. Path to a tool policy JSON file; defaults to |
| Optional. Comma-separated tiers to allow, e.g. |
| Optional. Comma-separated allowlist. When set, only these tools register |
| Optional. Comma-separated domains to keep (see Controlling the tool surface) |
| Optional. |
| Optional. Start-up wait for the application list, 0–30000 (default 2500) |
| Optional. Comma-separated tool names to deny, overriding every other rule |
|
|
| Per-request timeout; default |
| Keep-alive connection pool size; default |
| Retries for 503 responses; default |
| Separate budget for 429 waits; default |
| Ceiling on any single retry wait; default |
| Outgoing requests allowed per window, per route; default |
| Rate limit window; default |
| Optional ceiling across all routes, for servers that share an IP with other integrations; default |
| A call that would wait longer than this for a rate-limit slot fails at once instead of outliving the client's timeout; default |
| Rows fetched for |
|
|
| IANA time zone for rendered dates; defaults to the server's |
| Reference-data cache TTL; default |
| Search page cache TTL; default |
| Single-record and child-collection cache TTL; default |
| Bound on each cache; default |
|
|
|
|
| HTTP bind address; defaults to |
| HTTP port; defaults to |
| Bearer token for HTTP clients; required when |
| Optional comma-separated HTTP Host allowlist, recommended for remote deployments |
| Optional comma-separated browser Origin allowlist |
All configuration is validated once at startup; invalid or missing values fail fast with a single message listing every problem.
If no method is selected, admin key-based auth is preferred when both admin and user credentials are configured. SSO must be selected explicitly; its token lifecycle is separate from password/key authentication.
TEAMDYNAMIX_BASE_URL is normalized to the API root used by the server. For a
standard organization URL, the server calls
https://yourorg.teamdynamix.com/TDWebApi/api. For a sandbox or organization
with a custom Web API path, provide that path explicitly, for example:
TEAMDYNAMIX_BASE_URL=https://yourorg.teamdynamix.com/SBTDWebApiThis produces https://yourorg.teamdynamix.com/SBTDWebApi/api/auth/loginadmin
for admin authentication. Do not use the TDNext browser URL
(/SBTDNext/Login.aspx) as the API base URL.
Verify your setup
Run this after filling in .env to confirm authentication works and list your application IDs:
npm run verifyThe scripts sign in through the same code and configuration rules as the server, so if npm run verify succeeds the server will authenticate too, and a credentials mismatch (for example TEAMDYNAMIX_AUTH_METHOD=admin without TEAMDYNAMIX_BEID and TEAMDYNAMIX_WS_KEY) fails with the same message.
Running
stdio (default)
Recommended for Claude Desktop, VS Code Copilot, and other local clients:
npm startStreamable HTTP
Local HTTP uses 127.0.0.1:3000 by default:
npm run start:http
# MCP endpoint: http://127.0.0.1:3000/mcpFor a hosted deployment, set HOST=0.0.0.0, an MCP_AUTH_TOKEN of at least 24
characters (the server refuses to start with a shorter one on a non-loopback host;
generate one with node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"), and
MCP_ALLOWED_HOSTS to the public hostname. Terminate TLS at a reverse proxy or
hosting platform; major remote MCP clients require HTTPS. The HTTP transport is
stateless and supports JSON responses, so GET /mcp and DELETE /mcp return
405 Method Not Allowed with Allow: POST as permitted by the MCP specification.
Browser CORS preflights advertise only POST; GET and DELETE are not enabled as
cross-origin methods. Browser clients must use an origin listed in
MCP_ALLOWED_ORIGINS, while server-to-server MCP clients normally send no
Origin header.
Read and write capabilities
Every tool is classified into one of four capability tiers, which the tool policy uses to decide what a given deployment may do:
Tier | Meaning | Examples | Default |
| Changes nothing |
| allow |
| Adds new data; nothing existing is overwritten |
| allow |
| Overwrites fields on an existing record |
| deny |
| Deletes or unlinks existing data |
| deny |
The create/edit split follows TeamDynamix's own vocabulary. Posting to a
ticket's feed is an update — the normal technician workflow, additive, and
allowed by default. Writing a ticket's Title, Status, or Responsible fields is an
edit, and is denied unless a deployment opts in.
Read tools declare readOnlyHint: true. Everything else declares
readOnlyHint: false, and the edit and destroy tiers additionally declare
destructiveHint: true.
Client approval remains controlled by the MCP host. VS Code, Claude, ChatGPT, and OpenAI API applications can require confirmation before write calls. The TeamDynamix account configured on the server must itself have permission for the requested read or write operation.
Tool policy
config/tool-policy.json decides which tools are registered. Denied tools are
never advertised and cannot be invoked, so this is an enforcement boundary inside
the server rather than a client approval hint.
The checked-in policy allows read and create tools by default, while edit
and destroy tools are denied unless explicitly enabled through a domain rule,
tool rule, or environment override. The individual tool entries in the file
default to inherit, so the tier and domain rules remain the source of truth.
{
"$schema": "./tool-policy.schema.json",
"defaults": { "read": "allow", "create": "allow", "edit": "deny", "destroy": "deny" },
"domains": {
"tickets": { "edit": "allow" }, // technicians may edit tickets...
"cmdb": { "edit": "deny" } // ...but never the CMDB
},
"tools": {
"tdx_edit_ticket_task": "allow",
"tdx_remove_group_members": "deny"
},
"treatReadModifyWriteAsDestroy": false
}Rules are applied most specific first: TDX_DENY_TOOLS, then TDX_ALLOW_TOOLS,
then TDX_TOOLSETS, then tools, then domains, then defaults. A rule of "inherit" expresses no
opinion and falls through to the next layer. TEAMDYNAMIX_READ_ONLY=true
overrides everything and leaves only the read tier.
A few TeamDynamix endpoints have no PATCH, so those tools read the record and
write the whole thing back — a concurrent change is silently lost. Set
treatReadModifyWriteAsDestroy to true to judge them under the destroy tier.
An invalid or unreadable policy file is a startup failure; the server never falls back to a more permissive configuration. If the file is absent entirely, the built-in defaults above apply.
Run npm run policy:sync after adding or removing a tool to keep the tools map
in step with the catalog; a unit test fails if it drifts.
Controlling the tool surface
Some clients cap the number of tools they accept (GitHub Copilot in VS Code stops at 128 across all servers). Three layers keep this server's surface small; each only ever removes tools, none grants access.
Policy (above) — capability tiers, domains, allow and deny lists.
TDX_TOOLSETS— a coarse allowlist of domains, for exampleTDX_TOOLSETS=tickets,people,reports. Valid names:tickets,assets,cmdb,projects,issues,people,reports,auth. Authentication tools always stay. Reference lookups stay when they serve a listed domain; generic ones (accounts, locations, applications, custom attributes) always stay. It is evaluated afterTDX_DENY_TOOLSandTDX_ALLOW_TOOLSand beforetools,domainsanddefaults.Application gating (
TDX_APP_GATING=auto, the default) — at start-up the server reads/applicationsand does not register tools for an application kind the account lacks (Ticketing, Asset/CI, Projects). SetTDX_APP_GATING=offto disable it.TDX_APP_GATING_TIMEOUT_MS(default 2500) bounds how long start-up waits.
Prompts follow their tools: a prompt is offered only when every tool it uses is registered, so denying a tool or hiding its application also removes the prompts that depend on it.
Gating is a convenience, not a security boundary. It fails open: if the application list is unavailable, empty, or contains no recognized kind, every policy-allowed tool stays registered. A stdio server that could not resolve the list in time keeps retrying in the background and, once it succeeds, hides the unusable tools and sends a single tools/list_changed. Clients that ignore that notification keep their original list, and the server's instructions text stays as computed at start-up.
To see exactly what is registered and why, run npm run tools:explain (add -- --offline to skip the application lookup, or -- --hidden to list only unregistered tools). It prints application kinds, never application names.
Read-only server mode
For a server instance that must not expose write operations, set:
TEAMDYNAMIX_READ_ONLY=trueIn this mode, the server does not register any tool whose annotation is
readOnlyHint: false, so clients cannot discover or invoke those write tools.
It is still best practice to use a dedicated TeamDynamix account with only the
required read permissions, because API credentials are an independent defense
layer.
Using with VS Code (GitHub Copilot)
Add the server to your VS Code MCP configuration using one of the two methods below.
Option A — Workspace config (shared with your team)
Create or edit .vscode/mcp.json in your project:
{
"servers": {
"teamdynamix": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"TEAMDYNAMIX_BASE_URL": "${input:tdxBaseUrl}",
"TEAMDYNAMIX_BEID": "${input:tdxBeid}",
"TEAMDYNAMIX_WS_KEY": "${input:tdxWsKey}"
}
}
},
"inputs": [
{
"id": "tdxBaseUrl",
"type": "promptString",
"description": "TeamDynamix org or API URL (e.g. https://yourorg.teamdynamix.com or https://yourorg.teamdynamix.com/SBTDWebApi)"
},
{
"id": "tdxBeid",
"type": "promptString",
"description": "TeamDynamix admin BEID",
"password": false
},
{
"id": "tdxWsKey",
"type": "promptString",
"description": "TeamDynamix Web Services Key",
"password": true
}
]
}VS Code will prompt you for credentials on first use and store them securely — no secrets in source control.
Option B — User profile config (personal, all workspaces)
Open the Command Palette (Ctrl+Shift+P) → MCP: Open User Configuration, then add:
{
"servers": {
"teamdynamix": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/teamdynamix-mcp-server/dist/index.js"],
"env": {
"TEAMDYNAMIX_BASE_URL": "https://yourorg.teamdynamix.com",
"TEAMDYNAMIX_BEID": "your-beid",
"TEAMDYNAMIX_WS_KEY": "your-ws-key"
}
}
}
}Tip: Use
${input:...}variables (as shown in Option A) instead of hardcoding credentials even in your user profile config.
After saving, VS Code will prompt you to trust the server. Once trusted, all TeamDynamix tools will be available in GitHub Copilot chat (Ctrl+Alt+I).
Using with Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"teamdynamix": {
"command": "node",
"args": ["/absolute/path/to/teamdynamix-mcp-server/dist/index.js"],
"env": {
"TEAMDYNAMIX_BASE_URL": "https://yourorg.teamdynamix.com",
"TEAMDYNAMIX_BEID": "your-beid",
"TEAMDYNAMIX_WS_KEY": "your-ws-key"
}
}
}
}Using with ChatGPT and OpenAI
OpenAI Responses API
OpenAI's Responses API can call remote MCP servers over Streamable HTTP. Deploy
this server behind HTTPS and pass its bearer token in authorization:
const response = await openai.responses.create({
model: "gpt-5.6",
input: "Find my open TeamDynamix tickets and summarize them.",
tools: [{
type: "mcp",
server_label: "teamdynamix",
server_description: "Read and update TeamDynamix tickets, assets, CMDB, projects, people, and reports.",
server_url: "https://mcp.example.com/mcp",
authorization: process.env.MCP_AUTH_TOKEN,
require_approval: "always"
}]
});OpenAI requires approval by default before sharing data with a remote MCP server. Keep approval enabled for write tools; applications that trust the server can selectively skip approval for named read tools.
ChatGPT custom apps
ChatGPT custom apps can expose both read operations and write actions from an MCP
server. Use a publicly reachable HTTPS endpoint and configure app permissions so
changes require approval. MCP authorization is optional at the protocol level,
but this server intentionally requires MCP_AUTH_TOKEN when exposed remotely
because it holds TeamDynamix credentials and provides write actions.
The static bearer-token mode works directly with the OpenAI Responses API. A published or per-user ChatGPT app may require an MCP-compliant OAuth 2.1 resource server and authorization service instead; that user-delegated OAuth flow is not implemented here. Do not publish an unauthenticated instance.
OpenAI-compatible endpoints
MCP support belongs to the agent host/API implementation, not the model wire format. An endpoint that only emulates OpenAI Chat Completions is not automatically an MCP client. It works with this server when either:
the endpoint implements the OpenAI Responses API
type: "mcp"tool; oran MCP-aware host such as VS Code, Claude Desktop, Cursor, or Continue uses that endpoint as its model backend and calls this server separately.
For endpoints without either capability, use a client-side MCP-to-function-calling adapter; no change to this server is required.
Utility Scripts
Command | Description |
| Unit suite (vitest, no network): config, client, cache, pagination, cursors, search, tool framework |
| Build and verify discovery of all 64 read/write tools over stdio and authenticated HTTP, including auth, origin, method, and CORS preflight checks |
| Unit suite + script type-check + protocol test |
| Measure cold start, warm calls, cache hits, and search paging; accepts |
| Sweep search |
| Type-check all utility and protocol-test scripts |
| Authenticate (using the server's own login rules) and list all ticketing app IDs — run this first |
| Exercise every read endpoint; performs no writes |
| Write-path checks. Requires |
| List all applications grouped by type; supports |
| Search tickets from the CLI |
search-tickets options
--app-id <number> Required. Use `npm run list-apps` to find IDs
--limit <number> Max results (default: 25)
--offset <number> Pagination offset (default: 0)
--search <string> Free-text search
--requestor <email> Filter by requestor email
--is-open Only open tickets
--status-ids <n,n,…> Comma-separated status IDs
--priority-ids <n,n,…> Comma-separated priority IDs
--type-ids <n,n,…> Comma-separated type IDs
--json Output raw JSONNotes on the TeamDynamix API
app_idis required on most tools. It scopes requests to a specific TDX application (ticketing app, assets app, etc.). Runnpm run verifyor calltdx_list_applicationsto discover valid IDs.Reference data first: valid
type_id,status_id, andpriority_idvalues vary per org and per application. Usetdx_get_ticket_referenceandtdx_get_asset_referencebefore creating or updating records.Assets vs. CMDB: Assets live at
/{appId}/assets/...; Configuration Items live at/{appId}/cmdb/.... These are separate TDX namespaces with separate type/relationship systems.Search vs. get:
*_searchtools return partial records (no descriptions or custom attributes). Use the corresponding*_get_*tool for full details.Custom attributes: Pass
custom_attributes: [{ ID: number, Value: string }]to create/update tools. Usetdx_list_custom_attributes(component_id=9 for tickets, 63 for assets/CIs) to discover IDs and valid choice values.Reports:
tdx_get_report(withwith_data=true) andtdx_run_saved_searchare the most powerful read operations for complex queries — prefer these over chaining many search calls.Rate limits: TD commonly enforces 30–60 calls/60s per IP. The server auto-retries 429 and 503 responses with 2s then 4s exponential backoff before surfacing the error.
Performance architecture
Connection reuse: keep-alive HTTP(S) agents, so requests after the first skip the TLS handshake.
Proactive, per-route rate limiting: TeamDynamix limits individual methods, so each route (
POST /{id}/tickets/search) has its own sliding-window limiter that learns its real limit fromX-RateLimit-*headers and holds until the stated reset plus a 5 s margin. A 429 waits for that reset, elseRetry-After, else jittered backoff. A queued call reports progress when the client asked for it, and stops waiting when the client cancels; a write that was already sent is never aborted. A call that would wait longer thanTEAMDYNAMIX_MAX_QUEUE_WAIT_MSfails at once with the time to retry.Single-flight de-duplication: identical concurrent reads collapse into one upstream request. Writes are never coalesced, so two identical creates always produce two records.
Caching: three bounded TTL-LRU tiers — reference data (applications, types, statuses, priorities, locations, accounts, people) served with stale-while-revalidate so it is effectively instant after first use; search pages so paging and re-sorting never re-run a query; and record data (single records, feeds, tasks, relationships, members). A write purges the search and record tiers for its domain and deliberately leaves reference data intact.
Token warm-up and reuse: the JWT and application list are fetched in the background at startup, and
TEAMDYNAMIX_TOKEN_CACHE=filepersists the token (mode0600, in the per-user state folder) so short-lived CLI processes skip the login round trip.Bounded search window: TeamDynamix search endpoints have no offset parameter, so results are paged client-side. The first page fetches only what it needs; the moment an agent pages, the server pulls the whole 251-row window once and serves every later page from cache. (Measured on a sandbox: ~440 ms fixed cost plus ~1 ms per row, so widening once beats refetching per page.) Beyond that window the server steers agents to saved searches and reports. Cursors are signed against the search and sort they came from, so a replayed cursor fails loudly instead of returning rows from a different query.
Rate limiting is per process: the limiter protects a long-running server, but TeamDynamix enforces its quota per IP, so other processes or integrations can consume it. A 429 is therefore treated as a wait instruction rather than a failure: it honors
Retry-Afterup toTEAMDYNAMIX_MAX_RETRY_DELAY_MSand draws on its own budget (TEAMDYNAMIX_MAX_RATE_LIMIT_WAITS), so a shared-quota stall does not consume the retries reserved for genuine errors.Observability: structured JSON logs on stderr with per-request timing, cache hit/miss, and retry counts, plus
GET /healthzon the HTTP transport.
Run npm run bench before and after configuration changes to measure the impact.
Development
npm run dev # tsx watch — no build step needed
npm run build # tsc → dist/
npm test # vitest unit suite
npx @modelcontextprotocol/inspector node dist/index.js # interactive tool testingMigrating to 4.0
Every tool name changed prefix: teamdynamix_search_tickets is now tdx_search_tickets, and so on for all 55 existing tools. The part after the prefix is unchanged.
Policy files,
TDX_ALLOW_TOOLSandTDX_DENY_TOOLSthat name a 3.x tool still work: each name is translated to itstdx_successor (a deny stays a deny) and a warning names the new name. Update them to silence it;npm run policy:syncrewritesconfig/tool-policy.json.Client-side allowlists (a VS Code or Claude Desktop tool filter, an agent's tool list) are not translated. Rename those by hand.
Prompts and saved instructions that mention a tool by name need the new name.
run_saved_searchno longer takessort_order(a saved search defines its own order) andtdx_get_reportpages instead of printing 50 rows.Behaviour you may notice:
is_opennow returns what you expect, JSON responses carry the data in the text block, and dates render as ISO 8601 with a time zone.
Upgrading to 3.1
File token cache: if you use
TEAMDYNAMIX_TOKEN_CACHE=file, the token file now lives underTDX_HOME/tokens. The first run signs in again; delete the oldtdx-mcpfolder in your temp directory.HTTP on a network address:
MCP_AUTH_TOKENmust be at least 24 characters. Loopback servers are unchanged.Scripts: they now fail on a credentials mismatch the same way the server does.
Migrating to 3.0
Old tool | Replacement |
|
|
|
|
Policy files,
TDX_ALLOW_TOOLSandTDX_DENY_TOOLSthat name an old tool still work: each old name is translated, a deny on any of them denies the replacement, and a warning on stderr names it. Update them to the new names to silence the warning.Client-side allowlists (for example a VS Code or Claude Desktop tool filter) are not translated; update them by hand.
If one list in a request cannot be loaded, the others are still returned and that one shows an error line. If every list fails, the call fails.
Contributing: sensitive-content check
This repository is public. A zero-dependency scanner (scripts/check-sensitive.mjs) blocks credentials, TeamDynamix key GUIDs, tenant URLs, JWTs, institutional email addresses, forbidden files and organization-specific terms. Organization terms are stored only as SHA-256 hashes in config/sensitive-terms.sha256, so the list itself reveals nothing.
npm run check:sensitive # scan the whole tree
npm run check:package # verify what `npm publish` would ship
npm run hooks:install # run the scan on every commit
npm run sensitive:add-term # add a term (masked prompt; never pass it as an argument)Use example, yourorg or test- placeholders in code, tests, docs and issues. A finding prints a location and a masked excerpt, never the matched term. Credential-style and URL findings can be suppressed on the line with sensitive-scan: allow <rule> — <reason>; organization-term, metadata and forbidden-file findings cannot. CI runs the same scanner over the tree and the pushed range, plus gitleaks.
Project Structure
src/
├── index.ts # Loads config, picks a transport
├── lifecycle.ts # When availability is resolved, servers are built, late pruning runs
├── server.ts # One server instance: instructions, mounting, resources
├── shutdown.ts # Signal handling
├── transports/ # stdio and Streamable HTTP adapters over the lifecycle
├── surface/
│ ├── catalog.ts # Every tool and prompt the server ships
│ ├── resolve.ts # Pure: which are registered, denied or hidden, and why
│ └── mount.ts # The only code that registers them with the MCP SDK
├── config.ts # Single zod-validated environment parse
├── constants.ts # CHARACTER_LIMIT, pagination + search-window bounds
├── types.ts # Shared TS interfaces, paginate(), cursor codec
├── framework/
│ ├── defineTool.ts # Declarative tool contract: format policy, errors, caching, timing
│ ├── definePrompt.ts # Prompts as data, with the tools they use
│ └── annotations.ts # READ / CREATE / EDIT / DESTROY capability presets
├── policy/
│ ├── index.ts # Tool policy resolution and enforcement decisions
│ ├── load.ts # Reads and validates the policy file and env overrides; legacy tool names
│ ├── availability.ts # Which application kinds the account has
│ └── schema.ts # Zod schema for config/tool-policy.json
├── schemas/
│ └── common.ts # Reusable Zod schemas (AppIdSchema, PagingShape, etc.)
├── services/
│ ├── client.ts # Keep-alive, rate limiting, caching, dedup, retry
│ ├── errors.ts # Auth, permission and policy error classes
│ ├── rate-limiter.ts # Per-route sliding-window limiters that learn from X-RateLimit-* headers
│ ├── request-context.ts # Cancellation and progress for the running tool call
│ ├── names.ts # Application, reference and `me` names resolved to IDs before a handler runs
│ ├── budget.ts # Size budget: responses are cut at record boundaries
│ ├── fields.ts # `fields` projection and table rendering
│ ├── paged-search.ts # Server-side paging for saved searches
│ ├── cache.ts # Bounded TTL-LRU (expired entries swept on write) + search keys + invalidation
│ ├── search.ts # Cached search + client-side paging
│ ├── format.ts # Renderers and truncation
│ └── logger.ts # Structured stderr logging + counters
├── auth/ # Authorization adapters (service account, SSO), token stores, SSO lifecycle
├── resources/ # tdx:// reference-data resources
├── prompts/ # triage_ticket, weekly_ticket_report
└── tools/ # One definition array per domain
├── auth.ts
├── tickets.ts
├── assets.ts
├── cmdb.ts
├── projects.ts
├── issues.ts
├── people.ts
├── reference.ts
└── reports.ts
test/ # vitest unit suite
scripts/ # verify, list-apps, search-tickets, smoke-test, bench, protocol test; auth.ts wraps the server login
config/ # tool-policy.json and its JSON schemaLicense
MIT — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Manage tickets, run agents and workflows, query tables, and search workspace knowledge.
Every Canopy public API operation as a tool, run as you after a browser sign-in or on an API key.
Provides access to Civic Plus - See Click Fix, allowing you to interact with your data via an LLM.…
Access Pollinations models and API capabilities through agent tools.
Related MCP Servers
- FlicenseBqualityDmaintenanceAn MCP server that wraps the TeamDynamix (TDX) REST API, enabling AI-assisted IT service management through natural language. It exposes 41 tools for managing tickets, assets, CMDB, knowledge base articles, and other core TDX domains.411-
- AlicenseBqualityDmaintenanceEnables AI assistants to connect with Freshservice ITSM for managing tickets, assets, agents, and organizational data through natural language. It provides a comprehensive set of tools for performing CRUD operations on service desk records and searching across the Freshservice platform.531MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to interact with TeamDynamix ITSM operations including tickets, assets, KB, and more through safety-gated tools.50 npm3MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the TeamDynamix Web API, enabling AI assistants to search tickets, manage assets, query the knowledge base, and look up people in your TDX instance.1-