Teamdynamix

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 that route validated actions across discovery, tickets, relationships, KB, assets, CMDB, people, services, projects, time, and reference data
• Safe by default: write, delete, and admin tools disabled until explicitly opted in; destructive operations require confirm: true
• Two auth modes: standard (username/password) and admin (BEID/WebServicesKey)
• Covers 207 API endpoints across all TeamDynamix domains, verified against the SDK route manifest
• Rate-limit aware: SDK built-in retry with exponential backoff on 429 and 5xx 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

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
[email protected]    # 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", "@selfagency/teamdynamix-mcp"],
      "env": {
        "TEAMDYNAMIX_BASE_URL": "https://your-tenant.teamdynamix.com/TDWebApi",
        "TEAMDYNAMIX_AUTH_MODE": "standard",
        "TEAMDYNAMIX_USERNAME": "[email protected]",
        "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": "[email protected]",
        "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"

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.

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:

• 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

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