mcp-suite

mcp-suite

A production-grade TypeScript MCP server that gives AI agents (Claude Desktop, Cursor, Windsurf, custom agents) structured access to real-world data across four domains: financial markets, Web3/DeFi, developer tools, and healthcare (FHIR).

• Auth-first — JWT validation enabled by default
• Domain isolation — missing API keys disable one domain, not the whole server
• Response cache (LRU + TTL) and token-bucket rate limiting per domain
• Typed schemas (Zod) on every tool input and output
• Two transports: stdio (local) and HTTP + SSE (remote/hosted)

Quick Start

# Run directly (no global install required)
npx mcp-suite

# Or install globally
npm install -g mcp-suite
mcp-suite

Requirements: Node.js ≥ 20, npm ≥ 10

Installation

1. Set up environment variables

Copy .env.example to .env and fill in the keys for the domains you want to enable:

cp .env.example .env

# Authentication (required in production)
MCP_JWT_SECRET=your-secret-here

# Financial Markets (Alpha Vantage + CoinGecko)
ALPHA_VANTAGE_API_KEY=

# Web3 / DeFi (Alchemy + OpenSea + Blur)
ALCHEMY_API_KEY=
OPENSEA_API_KEY=

# Developer Tools (GitHub)
GITHUB_TOKEN=

# Healthcare / FHIR (optional — defaults to public HAPI sandbox)
FHIR_BASE_URL=https://hapi.fhir.org/baseR4

# Server
LOG_LEVEL=info         # debug | info | warn | error
MCP_PORT=3000          # HTTP transport only
AUTH_DISABLED=false    # set true for local dev only

You only need keys for the domains you use. Domains with missing keys are silently disabled at startup.

2. Generate a development token

npx mcp-suite gen-token
# eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Add to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mcp-suite": {
      "command": "npx",
      "args": ["mcp-suite"],
      "env": {
        "MCP_JWT_SECRET": "your-secret-here",
        "ALPHA_VANTAGE_API_KEY": "...",
        "ALCHEMY_API_KEY": "...",
        "OPENSEA_API_KEY": "...",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

4. Start as HTTP server (remote/hosted deployments)

npx mcp-suite --transport http --port 3000

This exposes GET /health, GET /tools, and the SSE endpoint for remote MCP clients.

CLI Commands

Available Tools

Financial Markets

Powered by Alpha Vantage and CoinGecko. Requires: ALPHA_VANTAGE_API_KEY

Example:

{ "tool": "get_stock_quote", "arguments": { "ticker": "NVDA" } }

Web3 / DeFi

Powered by Alchemy, OpenSea, and Blur. Requires: ALCHEMY_API_KEY, OPENSEA_API_KEY

Example:

{ "tool": "get_nft_floor", "arguments": { "collection_slug": "boredapeyachtclub" } }

Developer Tools

Powered by the GitHub API. Requires: GITHUB_TOKEN

Example:

{ "tool": "get_pipeline_status", "arguments": { "repo": "vercel/next.js", "branch": "canary" } }

Healthcare (FHIR)

Powered by HAPI FHIR R4. Requires: nothing (defaults to public sandbox) or FHIR_BASE_URL for custom endpoints.

HIPAA Notice: All healthcare tools connect to a public sandbox with synthetic data only. No real patient health information (PHI) is accessed. For production use, replace FHIR_BASE_URL with a HIPAA-compliant EHR endpoint and configure appropriate SMART on FHIR OAuth 2.0 credentials.

Example:

{ "tool": "lookup_patient", "arguments": { "name": "Smith", "birth_date": "1980-01-15" } }

Authentication

Authentication is enabled by default. Every tool call must carry a valid JWT.

Production

Set MCP_JWT_SECRET to a strong secret. The server refuses to start in production mode without it.

Development

Option A — disable auth entirely (local only):

AUTH_DISABLED=true

Option B — use a dev JWT:

npx mcp-suite gen-token

Pass the generated token in the MCP request _meta field (stdio) or the Authorization: Bearer header (HTTP).

JWT structure

{
  "sub": "your-client-id",
  "scope": "mcp:tools",
  "iat": 1713484800,
  "exp": 1716076800
}

Architecture

MCP Clients (Claude Desktop · Cursor · Windsurf · Custom Agents)
        │  MCP Protocol
┌───────▼────────────────────────────────────────┐
│  Transport Layer  (stdio  |  HTTP + SSE)        │
├────────────────────────────────────────────────┤
│  Auth Middleware  (JWT validation / bypass)     │
├────────────────────────────────────────────────┤
│  Tool Registry    (register · list · route)     │
├──────────┬──────────┬──────────┬───────────────┤
│Financial │  Web3    │ DevTools │  Healthcare   │
├──────────┴──────────┴──────────┴───────────────┤
│  Shared: Rate Limiter · Cache · Logger · Errors │
└─────────────────────────────────────────────────┘
         │           │          │          │
   Alpha Vantage  Alchemy   GitHub API  HAPI FHIR
   CoinGecko      OpenSea
                  Blur

• Caching: LRU + TTL in-process cache (node-cache). TTLs are domain-appropriate (15s for crypto, 300s for GitHub repo stats).
• Rate limiting: Token-bucket per domain protects free-tier API quotas.
• Error types: AuthError, ValidationError, DomainUnavailableError, UpstreamError, RateLimitError — all produce structured MCP error responses.
• Logging: Structured JSON on every tool call: domain, tool name, latency, cache hit, status.

Adding a Domain

Each domain follows the same pattern. To add a new domain:

1. Create src/domains/[name]/ with index.ts, schemas.ts, client.ts, and tools/
2. Export a Domain object:

export const myDomain: Domain = {
  name: 'my-domain',
  isAvailable: () => !!config.MY_API_KEY,
  registerTools: (server) => { /* server.tool(...) calls */ }
}

3. Register it in src/server.ts
4. Document tools in docs/API.md

See docs/TDD.md §5 and docs/CODING_STANDARDS.md for the full pattern.

Development

git clone https://github.com/ayenisholah/mcp-suite.git
cd mcp-suite
npm install
cp .env.example .env   # fill in your API keys

npm run build          # compile TypeScript → dist/
npm run dev            # watch mode
npm run typecheck      # type check without emit
npm run lint           # ESLint
npm test               # unit tests (Vitest)
npm run test:coverage  # tests + coverage report

# Integration tests — hits real APIs, requires .env keys
RUN_INTEGRATION=true npm test

HTTP Transport Endpoints

When running with --transport http:

Error Reference

License

MIT — see LICENSE

Contributing

Issues and PRs welcome. Please read docs/CODING_STANDARDS.md before submitting.