Verix API MCP Server

A production-ready Model Context Protocol server for the Verix API.

This template lets Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients search Verix records, retrieve record details, and run analysis workflows through controlled Verix API tools.

Built as a starter template for teams that want a secure baseline before adding company-specific Verix API automation, verification workflows, or AI-powered operational tooling.

Who this is for

This repository is useful for:

• developers building AI assistants on top of the Verix API,
• platform teams connecting Verix workflows to Claude, Cursor, or other MCP clients,
• agencies building custom Verix API integrations for clients,
• teams that need a clean TypeScript MCP server example,
• builders creating AI-powered search, record lookup, or analysis workflows.

Features

• TypeScript + Express MCP server
• Streamable HTTP MCP transport
• Verix API client with timeout and retry support
• API key protection for /mcp
• Rate limiting for MCP requests
• Health endpoint at /health
• Structured Pino logging
• Zod-based environment validation
• MCP tools for search, record retrieval, and analysis
• Jest + Supertest test setup
• GitHub Actions CI workflow

Architecture

Claude Desktop / Cursor / Windsurf
        │
        │  HTTP POST /mcp
        │  X-API-Key: <MCP_API_KEY>
        ▼
  Express Server
        │
        ├── Correlation ID middleware
        ├── Pino HTTP logger
        ├── Rate limiter
        ├── MCP API key middleware
        │
        ▼
   MCP SDK Handler
        │
        ├── verix_search       ─┐
        ├── verix_get_record   ─┤──► Verix REST API
        └── verix_analyze      ─┘

  GET /health → Verix API dependency status

See the larger diagram in docs/architecture.md.

Source Code

The complete production-ready Verix API MCP Server template is available on GitHub.

Repository:

https://github.com/kamolc4/verix-api-mcp-server

The repository includes:

• Complete TypeScript source code
• Verix API client
• MCP tools
• GitHub Actions CI
• Jest test suite
• MIT License
• Claude Desktop & Cursor configuration
• Production deployment examples

Fork the repository or download it as a ZIP to start building immediately.

Available MCP tools

Tool	Purpose
verix_search	Search Verix records using a full-text query with optional filters.
verix_get_record	Retrieve a full Verix record by ID, including metadata and timestamps.
verix_analyze	Run an analysis job on a Verix record, such as sentiment, classification, extraction, or summary.

Quick start

1. Install dependencies

# Clone repository
git clone https://github.com/kamolc4/verix-api-mcp-server.git

cd verix-api-mcp-server

# Install dependencies
npm ci

2. Configure environment

cp .env.example .env

Edit .env:

PORT=3000
NODE_ENV=development
LOG_LEVEL=info

MCP_API_KEY=replace-with-a-long-random-secret

VERIX_API_KEY=your-verix-api-key
VERIX_BASE_URL=https://api.verix.example.com/v1
VERIX_TIMEOUT_MS=10000
VERIX_MAX_RETRIES=3

RATE_LIMIT_RPM=60
RATE_LIMIT_WINDOW_MS=60000

3. Run locally

npm run dev

4. Check health

curl http://localhost:3000/health

5. List MCP tools

curl -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'X-API-Key: replace-with-your-mcp-api-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Verix API configuration

This starter uses API-key based access to the Verix API.

Required environment variables:

Variable	Description	Required
MCP_API_KEY	Shared secret required in the X-API-Key header for /mcp.	Yes
VERIX_API_KEY	API key used by this server to call the Verix API.	Yes
VERIX_BASE_URL	Base URL for the Verix REST API.	Yes
VERIX_TIMEOUT_MS	Timeout for outbound Verix API requests.	No
VERIX_MAX_RETRIES	Maximum retry attempts for retryable Verix API failures.	No
RATE_LIMIT_RPM	Max requests per rate-limit window.	No
RATE_LIMIT_WINDOW_MS	Rate-limit window duration in milliseconds.	No

The server sends Verix API requests with:

Authorization: Bearer <VERIX_API_KEY>

Connect to Claude Desktop

Build the server first:

npm run build
npm start

Then add an MCP server entry in your Claude Desktop configuration:

{
  "mcpServers": {
    "verix": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-API-Key": "replace-with-your-mcp-api-key"
      }
    }
  }
}

Restart Claude Desktop after editing the configuration.

Connect to Cursor

In Cursor, add a new MCP server using the HTTP endpoint:

{
  "name": "verix",
  "url": "http://localhost:3000/mcp",
  "headers": {
    "X-API-Key": "replace-with-your-mcp-api-key"
  }
}

Then restart Cursor or reload the MCP server list.

Security notes

This template is safer than a minimal demo, but you should harden it before production use.

Recommended production changes:

• Store MCP_API_KEY and VERIX_API_KEY in a managed secret manager.
• Rotate API keys regularly.
• Use separate Verix API keys for development, staging, and production.
• Add per-user or per-tenant authorization if multiple users will access the server.
• Add audit logs for every MCP tool call.
• Restrict write-capable tools behind approval workflows before adding them.
• Use HTTPS in production.
• Review Verix API permissions and use the minimum required access.
• Monitor rate limits and API errors.

Security Review

Verify this server with MCPForge:

https://www.mcpforge.tech/verify

MCPForge can help review:

• exposed tools,
• authentication behavior,
• health checks,
• compatibility with MCP clients,
• risk level of record analysis workflows,
• security posture before publishing or deployment.

After verification, you can link your public report from this README:

[![Verified by MCPForge](https://www.mcpforge.tech/api/badge/verified/verix-api-mcp)](https://www.mcpforge.tech/verified/verix-api-mcp)

Public MCPForge report:

https://www.mcpforge.tech/verified/verix-api-mcp

Starter template on MCPForge Code Hub:

https://www.mcpforge.tech/code/verix-api-mcp-server-starter

Deployment

A common production setup:

1. Deploy this service to Railway, Render, Fly.io, AWS, GCP, Azure, or a private Kubernetes cluster.
2. Configure environment variables in the hosting provider.
3. Set MCP_API_KEY and VERIX_API_KEY as secrets.
4. Set VERIX_BASE_URL to the correct production or sandbox Verix API endpoint.
5. Verify /health before connecting production MCP clients.
6. Verify /mcp with a valid X-API-Key.
7. Run a public or private verification with MCPForge.

Local development commands

npm run lint
npm run typecheck
npm test
npm run build

API endpoints

Method	Path	Description
GET	/health	Health and Verix API connectivity check.
POST	/mcp	MCP endpoint protected by X-API-Key.

Testing

npm test              # run all tests
npm run test:watch    # watch mode
npm run test:coverage # coverage report

The test suite covers:

• /health success and degraded states,
• missing API key on /mcp,
• invalid API key on /mcp,
• valid API key access,
• MCP tools/list,
• successful verix_search,
• Verix API failure handling,
• successful verix_get_record,
• successful verix_analyze,
• rate limit behavior,
• configuration validation.

Releases

Latest stable release:

v1.0.0

See the Releases page for the full changelog.

License

MIT — see LICENSE.

Related MCP Server Templates

Looking for other production-ready MCP Server templates?

• GitHub MCP Server
• Slack MCP Server
• Stripe MCP Server
• Notion MCP Server
• Shopify MCP Server
• HubSpot MCP Server
• PostgreSQL MCP Server

Browse the complete collection:

https://www.mcpforge.tech/code