teamdynamix-mcp
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 (unofficial)
A TypeScript Model Context Protocol (MCP) server that exposes TeamDynamix ITSM capabilities as agent-callable tools. Designed for AI agents and MCP clients that need structured, safety-gated access to TeamDynamix operations.
Features
11 domain gateway tools routing validated actions across discovery, tickets, relationships, KB, assets, CMDB, people, services, projects, time, and reference data
52 standalone tools plus the gateways β including a combined
get_ticketread (ticket + feed inlined,include_feed: falseopt-out) and SDK-backed people/KB searchesBulk tools:
bulk_get_tickets(parallel ticket+feed reads),bulk_update_tickets(sequential writes under the write gate),bulk_add_users_to_groupβ all capped at 25 items with per-item error isolationWorkspace watch tools: a local hash-diff ledger over the tickets you manage β diff passes, hidden-reply detection, ball-in-court inference, local-only notes, optional scheduled sweeps (
tdx-watch-sweepCLI + background triage)Safe by default: write, delete, and admin tools disabled until opted in; destructive operations require
confirm: true; watch tools are read-only toward TDXReal coverage of the live API: regenerated from the deployment OpenAPI spec (578 routes verified per-deployment); SDK exposes every live route incl. POST
Two auth modes: standard (username/password) and admin (BEID/WebServicesKey)
Rate-limit aware: SDK retry with exponential backoff on 429/5xx; runtime validation fails open in the MCP (zod boundary validation), compile-safe SDK validator
Zod-validated inputs: schema enforcement before any API call
Agent skill and prompt included: ready-to-use skill definition for GitHub Copilot and compatible agents
Related MCP server: Freshservice MCP Server
MCP Registry
This server is published to the MCP Registry as io.github.voxslopuli/teamdynamix-mcp.
Registry name:
io.github.voxslopuli/teamdynamix-mcpInstall via registry:
mcp-install io.github.voxslopuli/teamdynamix-mcp(when available)Manual install: Use npm package
@voxslopuli/teamdynamix-mcpas shown below
Quick start (developer setup)
This quick start is for contributors running the server from source in this
repository. If you are a regular MCP client user, skip to
MCP client configuration and use the npx
command examples.
# 1. Clone the repository
git clone https://github.com/voxslopuli/teamdynamix-mcp.git
cd teamdynamix-mcp
# 2. Install dependencies
pnpm install
# 3. Configure environment
cp .env.example .env
# Edit .env with your TeamDynamix credentials and base URL
# 4. Start the development server
pnpm devMinimum required environment variables
TEAMDYNAMIX_BASE_URL=https://your-tenant.teamdynamix.com/TDWebApi
TEAMDYNAMIX_AUTH_MODE=standard # or: admin
TEAMDYNAMIX_USERNAME=you@example.com # standard mode
TEAMDYNAMIX_PASSWORD=your-password # standard mode
# Optional: default application IDs (used when app_id is omitted in tool calls)
TEAMDYNAMIX_DEFAULT_TICKET_APP_ID=12345
TEAMDYNAMIX_DEFAULT_ASSET_APP_ID=23456
TEAMDYNAMIX_DEFAULT_KB_APP_ID=34567For admin mode, use TEAMDYNAMIX_BEID and TEAMDYNAMIX_WEB_SERVICES_KEY instead.
MCP client configuration
Security notice: Values shown above are placeholders. Never commit real credentials to source control. Inject secrets at runtime via a
.envfile (excluded by.gitignore), CI/CD secrets, or a secret manager.
VS Code (.vscode/mcp.json)
{
"servers": {
"teamdynamix": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@voxslopuli/teamdynamix-mcp"],
"env": {
"TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
"TEAMDYNAMIX_AUTH_MODE": "standard",
"TEAMDYNAMIX_USERNAME": "you@example.com",
"TEAMDYNAMIX_PASSWORD": "your-password"
}
}
}
}Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"teamdynamix": {
"command": "npx",
"args": ["-y", "@voxslopuli/teamdynamix-mcp"],
"env": {
"TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
"TEAMDYNAMIX_AUTH_MODE": "standard",
"TEAMDYNAMIX_USERNAME": "you@example.com",
"TEAMDYNAMIX_PASSWORD": "your-password"
}
}
}
}Production (built bundle)
pnpm build # outputs to dist/{
"command": "npx",
"args": ["-y", "@voxslopuli/teamdynamix-mcp"]
}Verify connectivity
After connecting your MCP client, call teamdynamix_discovery with:
action: "server_status"payload: {}response_format: "json"
A successful response shows status.configured: true.
Domain gateway tools
Each gateway tool accepts:
action: domain-specific operation namepayload: object for that actionβs parametersresponse_format:"markdown"or"json"
Domain | Gateway tool |
Discovery |
|
Tickets |
|
Ticket relationships |
|
Knowledge Base |
|
Assets |
|
CMDB |
|
People |
|
Services |
|
Projects |
|
Time |
|
Reference data |
|
β Requires confirm: true in addition to write tools being enabled.
All write/mutating actions require TEAMDYNAMIX_ENABLE_WRITE_TOOLS=true.
Workspace watch tools
A local, hash-diff ledger of tickets the agent manages (issue #19), plus local-only notes β the server's own memory. Strictly read-only toward TeamDynamix: none of these tools write to the API; drafts and sends stay human-owned.
Tool | Behavior |
| Diff pass: queue sweep per app, deep-fetch only changed tickets, classified deltas (status, new-entry, hidden-reply, ownership, sla, hold-window) |
| Ledger summary (counts, ball-in-court, oldest freshness). No TDX calls. |
| Add/update a ledger row (lane, ball-in-court override, next action). Never calls TDX. |
| Move a row to the archive; notes preserved. Never calls TDX. |
| Local notes CRUD on ledgered tickets ( |
Ledger file:
$TDX_WATCH_LEDGER(default./.tdx-watch-ledger.json). Atomic writes; corrupt files fail closed rather than being silently recreated.Ball-in-court (
us/them) is auto-inferred from the last feed entry's author; a manualballpassed towatch_registerwins permanently.TEAMDYNAMIX_US_UIDS(comma-separated) defines "us";TEAMDYNAMIX_AUTO_OBSERVE=trueenables bounded auto-observations on deep reads (default off).Note text is capped at 4000 chars; report bodies are length-capped and redacted (emails, phone-like runs).
Scheduled use: run
watch_check~2Γ/day (e.g.opencode runwith a watch-check prompt).
Automated sweep + background triage
TEAMDYNAMIX_TICKET_GROUP_IDS(optional, comma-separated): restricts ticket searches globally to those groups β applied client-side (the API does not applyGroupIDsserver-side on queue searches).TEAMDYNAMIX_WATCH_APP_IDS,TEAMDYNAMIX_WATCH_STATUS_IDS: scope new-unassigned discovery and the sweep's status filter.teamdynamix_watch_sweep: cheap sweep (no deep fetches) that maintains a localpendingTriagequeue: changed ledgered tickets + new unassigned tickets in the team's queues.teamdynamix_watch_triage(op: queue | done) lists/clears it after the agent has reviewed a ticket and updated its notes.In-session:
TEAMDYNAMIX_WATCH_SWEEP_SECS=900runs the same sweep on a timer while the MCP server is alive (only during sessions).Off-session:
tdx-watch-sweepCLI (headless, no LLM) +scripts/triage-prompt.md+scripts/org.voxslopuli.tdx-watch-sweep.plist(launchd, every 15 min): sweep, then run the harness triage prompt only when the queue is non-empty. Triage is read-only toward TDX β findings go to local notes; a human sends.
Bulk tools
Capped at 25 items per call; per-item errors are isolated so one bad item never aborts the batch.
Tool | Gate | Notes |
| read-only | Parallel ticket (+ feed) reads; |
| write gate | Sequential per-ticket patches (POST edits) to respect rate limits |
| write gate | SDK bulk helper with per-item isolation; |
Safety defaults
Flag | Default | Effect when |
|
| Enables all create/update/comment/mutation tools |
|
| Enables asset, CI, service, and service category deletion |
|
| Enables admin-scope operations |
Destructive operations additionally require confirm: true in the
tool call regardless of the flag state.
Agent skill
This repository ships a GitHub Copilot-compatible skill definition:
Skill:
skills/teamdynamix/SKILL.mdβ ID-first workflow patterns, safety branching rules, runbooks, gotchas, and tool catalogAgent prompt:
prompts/teamdynamix-agent.prompt.mdβ system prompt for agent mode with TeamDynamix context
Install the skill via your Copilot skill configuration
(see skills/teamdynamix/SKILL.md for full details).
Documentation
Section | Purpose |
Step-by-step setup and first workflows | |
Task-oriented recipes for real operations | |
Exhaustive tool catalog, configuration, safety model, errors | |
Architecture, auth model, safety rationale, rate limiting | |
Architecture, contributing, testing |
Development
pnpm typecheck # TypeScript strict checks
pnpm lint # oxlint
pnpm test # vitest (200+ tests, 90%+ coverage)
pnpm build # tsup β dist/License
MIT Β© The Self Agency LLC
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.
Search, reply, tag, assign and report on ThriveDesk help desk conversations from your AI assistant.
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
AI-native ITSM and ESM platform. resolve IT and HR requests inside Slack and Teams.
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
- AlicenseAqualityCmaintenanceEnables AI models to perform IT service management operations on Freshservice, including managing tickets, changes, problems, releases, assets, projects, and more through a set of MCP tools.362MIT
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to TeamDynamix, enabling natural language search and management of tickets, knowledge base, people, assets, projects, time entries, reports, service catalog, and custom attributes.1MIT