tdrest-mcp

A lightweight MCP (Model Context Protocol) server for making REST API calls to Teradata cloud services including:

• Elastic Compute — Manage compute engine clusters and configurations
• Enterprise Vector Store — Semantic search, RAG, and document ingestion
• OMS — Database management and object operations
• QueryGrid — Multi-system fabric connectivity

Supports custom authentication (Bearer JWT, Basic), Socks5 proxy routing, multipart file uploads, and progressive endpoint documentation.

Features

• Universal REST Client — Execute any HTTP method with custom headers, auth, and request bodies
• Bearer & Basic Auth — JWT tokens, username/password, custom headers with session persistence
• Socks5 Proxy — Route through corporate proxies with optional auth
• Multipart Uploads — Upload files combined with form fields (CSV, JSON, PDF, etc.)
• Semantic Search — Search Vector Store collections with natural language queries
• RAG Pattern — Retrieve documents + generate AI responses in one call
• Progressive Help — Searchable endpoint documentation with examples and parameters
• 50+ Endpoints — Auto-generated from Swagger specs (Elastic Compute, Vector Store, OMS, QueryGrid, etc.)
• Swagger Auto-Parser — Endpoints loaded at startup; no hand-curation needed
• Usage Guides — Best practices, workflows, and examples via searchable markdown guides
• Hot-loadable APIs — Drop a Swagger spec in specs/ → restart → instant access
• Dynamic Service URLs — Define any service via *_BASE_URL environment variables
• Stateless Design — All compute logic lives in the cloud APIs; MCP just brokers requests

Quick Start

Prerequisites

• Node.js 18+ with npm

Installation

git clone <repo-url>
cd tdrest-mcp
npm install
npm run build

Configuration

Copy .env.example to .env and set your API base URLs:

cp .env.example .env
# Edit .env with your values

Run the MCP Server

npm start

The server listens on stdin/stdout and is ready to accept tool calls from Claude.

Connect to Claude Desktop

Edit ~/.claude/config.json (or equivalent) to include:

{
  "mcp-servers": {
    "tdrest": {
      "command": "node",
      "args": ["/path/to/tdrest-mcp/dist/index.js"],
      "env": {
        "ELASTIC_COMPUTE_BASE_URL": "https://preprod.globalcompute.qateradatacloud.com"
      }
    }
  }
}

Restart Claude Desktop, and the tools will appear in the tool menu.

Usage

Set Authentication

User: "Authenticate with my Teradata JWT token"
Claude executes: set_auth {
  type: "bearer",
  token: "eyJhbGc..."
}

Make a REST Call

User: "List all clusters"
Claude executes: execute_rest_call {
  url: "https://preprod.globalcompute.qateradatacloud.com/clusters",
  method: "GET",
  // auth is applied automatically from session
}

Get Help on Endpoints

User: "What endpoints are available for clusters?"
Claude executes: get_syntax_help {
  query: "clusters"
}
Response:
  Found 2 endpoints matching "clusters":
  - GET /clusters — List all compute engine clusters for a site
  - POST /clusters — Create a new compute engine cluster
  ...

Get Usage Guides

User: "How do I set up a cluster?"
Claude executes: get_usage_guide {
  query: "cluster"
}
Response:
  Creating and Managing Clusters guide showing:
  - Step-by-step workflow
  - Config vs cluster distinction
  - Lifecycle management
  - Common errors and fixes

Upload a File

User: "Upload a document to the vector store"
Claude executes: execute_rest_call {
  url: "https://api.vectorstore.qateradatacloud.com/documents",
  method: "POST",
  files: {
    "document": { path: "/tmp/document.pdf" }
  },
  formData: {
    "collection_id": "my-collection"
  }
}

Project Structure

src/
├── index.ts              # MCP server + tool handlers
├── rest-client.ts        # HTTP client (axios + auth + proxy)
├── syntax-help.ts        # Endpoint registry and search
├── usage-guide.ts        # Usage guide registry
├── guide-loader.ts       # Auto-load guides from guides/ directory
├── swagger-parser.ts     # Swagger spec parser (auto-generates endpoints)
├── file-utils.ts         # File discovery and glob expansion
├── types.ts              # TypeScript interfaces
└── config.ts             # Environment config

specs/
├── global-compute-api.json        # Global Compute API (37 endpoints)
├── global-consumption-api.json    # Global Consumption API (3 endpoints)
└── vector-store-api.json          # Vector Store API (13 endpoints)

guides/
├── getting-started.md       # Quick introduction and basic workflows
├── clusters-setup.md        # Step-by-step cluster provisioning
└── error-handling.md        # Error codes and troubleshooting

tests/
└── ...                  # Unit tests

CLAUDE.md              # Detailed developer guide

Development

# Watch for TypeScript changes
npm run dev

# Run tests
npm test

# Run a single test
npm test -- src/path/to/test.spec.ts

# Lint
npm run lint
npm run lint:fix

Authentication & Security

• Bearer Tokens: Tokens are stored in memory for the session and not persisted to disk.
• Basic Auth: Username/password stored in memory; not logged.
• Custom Headers: Any header can be set per-request or per-session.
• HTTPS Only: All connections are HTTPS by default; HTTP is not enforced but discouraged.

Important: Do not commit credentials to the repository. Use environment variables or .env files (which are in .gitignore).

Proxy Support

User: "Route through a Socks5 proxy at proxy.corp.com:1080"
Claude executes: set_proxy {
  type: "socks5",
  host: "proxy.corp.com",
  port: 1080,
  username: "user",      // optional
  password: "pass"       // optional
}

All subsequent requests route through the proxy until set_proxy { type: "none" } is called.

Adding New API Specs

The server auto-loads endpoints from Swagger/OpenAPI specs. To add a new API:

1. Place the Swagger spec in specs/my-api.json
2. Restart the server — endpoints load automatically at startup
3. Search with get_syntax_help — all endpoints are immediately searchable

No code changes needed! Example:

# Copy your Swagger spec
cp /path/to/new-api-swagger.json specs/new-api.json

# Restart the server
npm start

# Now Claude can search and use all endpoints from new-api.json

The parser extracts:

• Endpoint path and HTTP method
• Parameter names, types, and requirements
• Request body schema properties
• Operation summary and description
• Response descriptions and examples
• Tags for better discoverability

Adding Usage Guides

Create markdown guides in guides/ to document best practices and workflows:

1. Create a new file — guides/my-guide.md
2. Add YAML frontmatter (optional):

   ---
   title: My Guide Title
   description: One-line description
   tags: [tag1, tag2]
   ---
   

3. Write markdown content — Guidelines, workflows, examples
4. Restart the server — Guides auto-load at startup
5. Search with get_usage_guide — Guides are immediately discoverable

No code changes needed! Users can then search by:

• Guide name: get_usage_guide("my-guide")
• Keyword: get_usage_guide("cluster")
• List all: get_usage_guide("list")

Limitations

• No auto token refresh — If a JWT expires, call set_auth again with a fresh token
• No request templating (yet) — Request bodies are literal; Handlebars templating planned
• No response filtering (yet) — Full responses returned; jq-like queries planned
• Blocking uploads — Large files block the connection; chunking coming in Phase 2

Documentation

• README.md — This file; user-facing feature overview
• CLAUDE.md — Deep architecture guide for developers
• DEPLOYMENT.md — Claude Desktop and VS Code integration
• VECTOR_STORE_ADDED.md — Vector Store API reference
• PROJECT_SUMMARY.md — Project structure and roadmap

Supported APIs

Service	Status	Endpoints	Auth
Global Compute	✅ Complete	37 (clusters, configs, OMS, QueryGrid, site-settings)	Bearer, Basic
Vector Store	✅ Complete	13 (collections, search, ingest, permissions, health)	Bearer, Basic
Any REST API	✅ Supported	Unlimited (universal client)	Bearer, Basic, Custom

Contributing

See CLAUDE.md for architectural details, testing patterns, and guidelines for adding endpoints.

License

MIT

Support

• Bug reports — GitHub Issues
• Feature requests — GitHub Discussions
• Architecture questions — See CLAUDE.md Q&A section
• Deployment help — See DEPLOYMENT.md troubleshooting