TeamDynamix MCP Server

An MCP server that connects AI assistants to your TeamDynamix instance. Search and manage tickets, knowledge base articles, people, assets, projects, time entries, reports, service catalog, and custom attributes through natural language.

Features

• Decision-tree navigation — only 2 tools load at startup; domain tools load on demand
• 9 domains — Tickets, Knowledge Base, People, Assets, Projects, Time, Reports, Service Catalog, Attributes
• 38 tools total across all domains
• Interactive elicitation — prompts for ticket type, asset status/form, KB category, time type, and service category when IDs aren't provided
• Claude plugin — skills and commands for guided workflows
• Multiple transports — stdio (default) and streamable HTTP

Available Tools

Always loaded

Tool	Description
tdx_navigate	Load a domain tool set (tickets, knowledge_base, people, assets, projects, reports, time, service_catalog, attributes)
tdx_status	Server status and loaded domains

Tickets domain

Tool	Description
tdx_tickets_search	Search tickets by text, status, priority, type, group
tdx_tickets_get	Get full ticket details by ID
tdx_tickets_create	Create a new ticket (interactive type selection)
tdx_tickets_update	Update an existing ticket

Knowledge Base domain

Tool	Description
tdx_kb_search	Search KB articles
tdx_kb_get_article	Get full article content
tdx_kb_create_article	Create a new KB article (interactive category selection)
tdx_kb_get_categories	List all KB categories

People domain

Tool	Description
tdx_people_search	Search people by name, email, or department
tdx_people_get	Get person details by UID

Assets domain

Tool	Description
tdx_assets_search	Search assets/CIs
tdx_assets_get	Get asset details by ID
tdx_assets_create	Create a new asset (interactive status/form selection)

Projects domain

Tool	Description
tdx_projects_search	Search projects by text, status, account
tdx_projects_get	Get full project details by ID
tdx_projects_create	Create a new project
tdx_projects_update	Update an existing project

Time domain

Tool	Description
tdx_time_search	Search time entries by date range and resource
tdx_time_get	Get full time entry details by ID
tdx_time_create	Log a new time entry (interactive type selection)
tdx_time_update	Update an existing time entry
tdx_time_delete	Delete a time entry
tdx_time_get_types	List all available time types

Reports domain

Tool	Description
tdx_reports_search	Search reports by name
tdx_reports_get	Get report metadata by ID
tdx_reports_execute	Execute a report and return data rows

Service Catalog domain

Tool	Description
tdx_services_search	Search the service catalog
tdx_services_get	Get full service details by ID
tdx_services_create	Create a new service (interactive category selection)
tdx_services_update	Update an existing service
tdx_services_search_offerings	Search offerings within a service
tdx_services_get_offering	Get full offering details
tdx_services_create_offering	Create a new offering within a service
tdx_services_update_offering	Update an existing offering
tdx_services_get_categories	List all service categories

Attributes domain

Tool	Description
tdx_attributes_list	List custom attribute definitions for a component
tdx_attributes_get_choices	Get picklist choices for an attribute
tdx_attributes_create_choice	Add a new picklist choice
tdx_attributes_update_choice	Update an existing picklist choice
tdx_attributes_delete_choice	Remove a picklist choice

Prerequisites

• Node.js 20+
• A TeamDynamix instance with API access enabled
• Admin service account credentials (BEID + Web Services Key)

Finding your credentials

1. Log into TDAdmin at https://yourinstance.teamdynamix.com/TDAdmin
2. Go to Organization Details → Security section
3. Copy the Web Services BEID and Web Services Key
4. You need the "Add BE Administrators" permission to see these values

Installation

Claude Plugin Marketplace

Install as a Claude Code plugin with guided skills and workflows:

/plugin marketplace add chatt-state/teamdynamix-mcp-server
/plugin install teamdynamix@teamdynamix-mcp-server

Set the required environment variables:

export TDX_BASE_URL=https://yourinstance.teamdynamix.com
export TDX_BEID=your-beid-guid
export TDX_WEB_SERVICES_KEY=your-web-services-key

Claude Desktop / Claude Code

Add to your MCP config (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "teamdynamix": {
      "command": "npx",
      "args": ["-y", "--registry", "https://npm.pkg.github.com", "@chatt-state/teamdynamix-mcp-server"],
      "env": {
        "TDX_BASE_URL": "https://yourinstance.teamdynamix.com",
        "TDX_BEID": "your-beid-guid",
        "TDX_WEB_SERVICES_KEY": "your-web-services-key"
      }
    }
  }
}

Docker

docker run --rm -i \
  -e TDX_BASE_URL=https://yourinstance.teamdynamix.com \
  -e TDX_BEID=your-beid-guid \
  -e TDX_WEB_SERVICES_KEY=your-web-services-key \
  ghcr.io/chatt-state/teamdynamix-mcp-server:latest

Docker MCP Gateway

The Docker image includes MCP Gateway metadata for auto-discovery:

docker mcp server enable teamdynamix-mcp-server \
  --image ghcr.io/chatt-state/teamdynamix-mcp-server:latest

From source

git clone https://github.com/chatt-state/teamdynamix-mcp-server.git
cd teamdynamix-mcp-server
npm install
npm run build

Configuration

Environment Variable	Required	Description
TDX_BASE_URL	Yes	Your TeamDynamix instance URL
TDX_BEID	Yes	API BEID (GUID format)
TDX_WEB_SERVICES_KEY	Yes	API Web Services Key (GUID format)
TDX_TICKETING_APP_ID	No	Ticketing app ID
TDX_ASSETS_APP_ID	No	Assets/CI app ID
TDX_KB_APP_ID	No	Knowledge Base app ID
TDX_SERVICE_CATALOG_APP_ID	No	Service Catalog app ID
TDX_MCP_TRANSPORT	No	stdio (default) or http

Usage

Once connected, ask your AI assistant things like:

• "Search for open tickets about VPN issues"
• "Look up the KB article about password resets"
• "Find all assets assigned to the IT department"
• "Create a ticket for a new laptop request"
• "Show me all active projects"
• "Log 2 hours against ticket #12345"
• "Run the monthly SLA report"
• "Search the service catalog for email services"
• "List the custom attributes on tickets"

The assistant will automatically load the relevant domain tools via tdx_navigate before executing searches.

Architecture

The server uses a decision-tree lazy loading pattern:

1. On startup, only tdx_navigate and tdx_status are registered
2. When the AI calls tdx_navigate("tickets"), the tickets domain tools load dynamically
3. The server notifies the client via tools/list_changed
4. Subsequent calls use the newly registered domain tools

This keeps the initial tool footprint small — important for LLMs with limited tool context.

Documentation

Full documentation at chatt-state.github.io/teamdynamix-mcp-server

Development

npm run build      # Compile TypeScript
npm run test       # Run tests (vitest)
npm run lint       # ESLint + format checks
npm run typecheck  # TypeScript type checking

License

MIT