TDX MCP Server
uidaho-nsummers/tdx-cli-mcp
MCP server para TeamDynamix — tickets, ativos e KB via IA
Ver no GitHubServidor MCP que encapsula a API Web do TeamDynamix, permitindo que agentes de IA (Claude Code, GitHub Copilot) pesquisem tickets, gerenciem ativos, consultem a base de conhecimento e busquem pessoas na sua instância TDX. Construído em TypeScript com autenticação robusta e rate-limiting.
Instalação
npx convez-ai uidaho-nsummers/tdx-cli-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar buscas e criação de tickets no TeamDynamix via Claude Code
- Consultar base de conhecimento e histórico de ativos durante desenvolvimento
- Integrar TeamDynamix com agentes de IA para triagem e gestão de demandas
Veredito

Solução sólida e bem estruturada para integrar TeamDynamix com Claude e GitHub Copilot. Excelente para equipes que usam TDX e querem automatizar interações via IA; requer credenciais administrativas e conhecimento prévio do TeamDynamix para configuração inicial.
README
A tradução para o português deste README ainda está na fila.
TDX MCP Server
An MCP (Model Context Protocol) server that wraps the TeamDynamix Web API, enabling AI assistants to search tickets, manage assets, query the knowledge base, and look up people in your TDX instance.
Quickstart
Prerequisites
- Node.js v26.3+ (with npm)
- A TeamDynamix instance with Web API access
- Admin service account credentials (BEID + Web Services Key)
1. Install dependencies
npm install
2. Configure environment
cp .env.example .env
Edit .env with your TDX instance details:
TDX_BASE_URL=https://yourinstance.teamdynamix.com/TDWebApi/api
TDX_BEID=your-admin-beid-guid
TDX_WEB_SERVICES_KEY=your-web-services-key-guid
TDX_TICKETING_APP_ID=123
TDX_ASSET_APP_ID=456
TDX_KB_APP_ID=789
Finding your App IDs: If you don't know your application IDs, you can discover them after setup using the tdx_applications_list tool, or by calling GET /api/applications on your TDX instance directly.
3. Run the server
npm start
(Equivalent to npx tsx packages/mcp/src/index.ts — tsx executes TypeScript directly under Node.js.)
The server communicates over stdio using the MCP protocol. It's designed to be launched by an MCP client (like Claude Desktop or Claude Code), not run standalone.
4. Connect to an MCP client
Claude Desktop (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"tdx": {
"command": "npx",
"args": ["-y", "tsx", "/absolute/path/to/packages/mcp/src/index.ts"],
"env": {
"TDX_BASE_URL": "https://yourinstance.teamdynamix.com/TDWebApi/api",
"TDX_BEID": "your-beid",
"TDX_WEB_SERVICES_KEY": "your-key",
"TDX_TICKETING_APP_ID": "123",
"TDX_ASSET_APP_ID": "456",
"TDX_KB_APP_ID": "789"
}
}
}
}
Claude Code (.claude/settings.json):
{
"mcpServers": {
"tdx": {
"command": "npx",
"args": ["-y", "tsx", "/absolute/path/to/packages/mcp/src/index.ts"]
}
}
}
When using Claude Code, place your credentials in .env at the project root (it's gitignored). Note: dotenv/config loads .env from the current working directory; if the server is launched from elsewhere, set DOTENV_CONFIG_PATH=/absolute/path/to/.env (or configure the client to run with the repo as its working directory).
Running tests
# All tests (unit + QA)
npm test
# Watch mode
npm run test:watch
Tests run under Vitest, which isolates module mocks per file natively.
Workspace scaffold
This repository uses npm workspaces for the planned library-first refactor:
packages/core—@tdx/core, shared TeamDynamix config, auth, API client, and rate-limit logicpackages/cli—tdx, reserved for the future command-line interfacepackages/mcp—@tdx/mcp, thin MCP wrapper over@tdx/core
The MCP server implementation lives in packages/mcp. Root src/ keeps compatibility entrypoints that delegate to the package source.
Project structure
packages/
core/
package.json # @tdx/core workspace package scaffold
src/index.ts # Core public API entrypoint
src/config.ts # Env var loading with Zod validation
src/auth/client.ts # TDX auth - JWT caching, proactive refresh
src/api/client.ts # Fetch wrapper - auth headers, retry on 429
src/api/rate-limiter.ts # Client-side sliding window rate limiter
src/operations/ # Domain operations returning raw TDX data
src/schemas/ # Zod input schemas for each operation
tsconfig.json # TypeScript project reference target
cli/
package.json # tdx workspace package scaffold with bin metadata
src/index.ts # Minimal CLI entrypoint placeholder
tsconfig.json # References @tdx/core
mcp/
package.json # @tdx/mcp workspace package metadata
src/index.ts # Entry point — stdio transport, graceful shutdown
src/server.ts # MCP server — tool registration
src/utils.ts # safeToolCall error wrapper + textResult helper
tests/qa/ # End-to-end MCP server tests
src/
index.ts # Compatibility entrypoint delegating to packages/mcp
server.ts # Compatibility re-export from packages/mcp
config.ts # Transitional re-export from @tdx/core
auth/
client.ts # Transitional re-export from @tdx/core
schemas.ts # Auth Zod schemas
api/
client.ts # Transitional re-export from @tdx/core
rate-limiter.ts # Transitional re-export from @tdx/core
tools/
utils.ts # Compatibility re-export from packages/mcp
tests/
config.test.ts # Config loading tests
auth/ # Auth client tests
api/ # API client + rate limiter + error scenario tests
operations/ # Core domain operation + schema tests
tsconfig.json # Solution-style TypeScript project references
tsconfig.root.json # Transitional root source and shared tests
tsconfig.base.json # Shared compiler options
Authentication
The server uses TDX admin authentication (POST /api/auth/loginadmin) with BEID and Web Services Key. The JWT is cached in memory and refreshed automatically 5 minutes before expiry (tokens last 24 hours).
Rate limiting
TDX enforces per-endpoint rate limits with no response headers. The server tracks limits client-side using a sliding window algorithm. Limits vary by endpoint:
| Endpoint | Limit |
|---|---|
| Ticket search | 30 / 60s |
| Ticket create | 120 / 60s |
| People CRUD | 45 / 60s |
| People lookup | 75 / 10s |
| Most others | 60 / 60s |
On 429 responses, the server retries up to 3 times with backoff.
Tech stack
- Runtime: Node.js (v26.3+) executed via tsx
- Language: TypeScript (strict mode)
- MCP SDK: @modelcontextprotocol/server
- Validation: Zod
- Linting/Formatting: Biome
- Testing: Vitest