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

• 20+ Endpoints — Elastic Compute, Vector Store, OMS, QueryGrid fully documented

• Stateless Design — All compute logic lives in the cloud APIs; MCP just brokers requests

Related MCP server: MCP REST Server

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
  ...

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
├── types.ts           # TypeScript interfaces
└── config.ts          # Environment config

specs/
└── elastic-compute-api.json   # Swagger spec snapshot

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.

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

• Swagger auto-parsing pending — Endpoints hand-curated; auto-generation from swagger specs 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

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