Skip to main content
Glama
teamdynamix-mcp

teamdynamix-mcp

by voxslopuli

🎟️ TeamDynamix MCP Server (unofficial)

NPM Version CI codecov

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_ticket read (ticket + feed inlined, include_feed: false opt-out) and SDK-backed people/KB searches

  • Bulk 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 isolation

  • Workspace 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-sweep CLI + 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 TDX

  • Real 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-mcp

  • Install via registry: mcp-install io.github.voxslopuli/teamdynamix-mcp (when available)

  • Manual install: Use npm package @voxslopuli/teamdynamix-mcp as 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 dev

Minimum 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=34567

For 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 .env file (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 name

  • payload: object for that action’s parameters

  • response_format: "markdown" or "json"

Domain

Gateway tool

Discovery

teamdynamix_discovery

Tickets

teamdynamix_tickets

Ticket relationships

teamdynamix_ticket_relationships

Knowledge Base

teamdynamix_knowledge_base

Assets

teamdynamix_assets

CMDB

teamdynamix_cmdb

People

teamdynamix_people

Services

teamdynamix_services

Projects

teamdynamix_projects

Time

teamdynamix_time

Reference data

teamdynamix_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

teamdynamix_watch_check

Diff pass: queue sweep per app, deep-fetch only changed tickets, classified deltas (status, new-entry, hidden-reply, ownership, sla, hold-window)

teamdynamix_watch_status

Ledger summary (counts, ball-in-court, oldest freshness). No TDX calls.

teamdynamix_watch_register

Add/update a ledger row (lane, ball-in-court override, next action). Never calls TDX.

teamdynamix_watch_archive

Move a row to the archive; notes preserved. Never calls TDX.

teamdynamix_watch_notes

Local notes CRUD on ledgered tickets (op: add | update | delete | list). Never written to TDX.

  • 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 manual ball passed to watch_register wins permanently.

  • TEAMDYNAMIX_US_UIDS (comma-separated) defines "us"; TEAMDYNAMIX_AUTO_OBSERVE=true enables 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 run with 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 apply GroupIDs server-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 local pendingTriage queue: 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=900 runs the same sweep on a timer while the MCP server is alive (only during sessions).

  • Off-session: tdx-watch-sweep CLI (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

teamdynamix_bulk_get_tickets

read-only

Parallel ticket (+ feed) reads; include_feed: false skips feed reads

teamdynamix_bulk_update_tickets

write gate

Sequential per-ticket patches (POST edits) to respect rate limits

teamdynamix_bulk_add_users_to_group

write gate

SDK bulk helper with per-item isolation; dry_run supported

Safety defaults

Flag

Default

Effect when true

TEAMDYNAMIX_ENABLE_WRITE_TOOLS

false

Enables all create/update/comment/mutation tools

TEAMDYNAMIX_ENABLE_DELETE_TOOLS

false

Enables asset, CI, service, and service category deletion

TEAMDYNAMIX_ENABLE_ADMIN_TOOLS

false

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:

Install the skill via your Copilot skill configuration (see skills/teamdynamix/SKILL.md for full details).

Documentation

Section

Purpose

Tutorials

Step-by-step setup and first workflows

How-to guides

Task-oriented recipes for real operations

Reference

Exhaustive tool catalog, configuration, safety model, errors

Explanation

Architecture, auth model, safety rationale, rate limiting

Development

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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      An 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.
      41
      1
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      53
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      36
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects 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.
      1
      MIT