# Verix API MCP Server

[![CI](https://github.com/kamolc4/verix-api-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/kamolc4/verix-api-mcp-server/actions/workflows/ci.yml)
[![Verified by MCPForge](https://www.mcpforge.tech/api/badge/verified/verix-api-mcp)](https://www.mcpforge.tech/verified/verix-api-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```text
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](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

```bash
# 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

```bash
cp .env.example .env
```

Edit `.env`:

```bash
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

```bash
npm run dev
```

### 4. Check health

```bash
curl http://localhost:3000/health
```

### 5. List MCP tools

```bash
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:

```text
Authorization: Bearer <VERIX_API_KEY>
```

## Connect to Claude Desktop

Build the server first:

```bash
npm run build
npm start
```

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

```json
{
  "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:

```json
{
  "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:

```md
[![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

```bash
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

```bash
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](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