🎟️ 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 that route validated actions across discovery, tickets, relationships, KB, assets, CMDB, people, services, projects, time, and reference data

• Safe by default: write tools disabled until explicitly opted in; destructive operations require confirm: true

• Two auth modes: standard (username/password) and admin (BEID/WebServicesKey)

• Rate-limit aware: auto-retry with backoff on 429 responses

• 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.selfagency/teamdynamix-mcp.

• Registry name: io.github.selfagency/teamdynamix-mcp

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

• Manual install: Use npm package @selfagency/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/selfagency/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

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", "@selfagency/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", "@selfagency/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", "@selfagency/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"

† Requires confirm: true in addition to write tools being enabled.

All write/mutating actions require TEAMDYNAMIX_ENABLE_WRITE_TOOLS=true.

Safety defaults

Destructive unlink operations additionally require confirm: true in the tool call regardless of write 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 catalog

• Agent 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

Development

pnpm typecheck   # TypeScript strict checks
pnpm lint        # oxlint
pnpm test        # vitest (194 tests, 87% coverage)
pnpm build       # tsup → dist/

License

MIT © The Self Agency LLC