Vendor-Accreditation MCP Server

A TypeScript MCP (Model Context Protocol) server for a Procurement Agency's vendor-accreditation system, deployed as a stateless web service on Google Cloud Run with a MongoDB Atlas backend.

Features

Exposes four tools for managing vendor accreditation data:

• list_expiring_vendors(daysAhead: number) — Returns vendors whose accreditation will expire within the next N days (only returns active vendors).

• get_vendor(vendorId: string) — Retrieves the full vendor record including accreditation status, expiry date, and audit history.

• update_accreditation_status(vendorId: string, status: 'Active' | 'Expired' | 'Suspended', reason: string) — Updates a vendor's status and records the change in an audit log. Requires an accreditationExpiryDate in the future if setting status to 'Active'.

• search_vendors(query: string, category?: string) — Performs case-insensitive free-text search across vendor names and categories.

Related MCP server: comprasal-mcp

Prerequisites

• Node.js 22+ (for native mongodb driver and ES2022 support)

• MongoDB Atlas cluster (or any MongoDB instance reachable over the network)

• Google Cloud project (for Cloud Run deployment)

Local Development

Setup

1. Install dependencies:

   npm install

2. Create a .env file from the example:

   cp .env.example .env

3. Update .env with your MongoDB Atlas connection string:

   MONGODB_URI=mongodb+srv://<username>:<password>@<cluster-host>/<database>?retryWrites=true&w=majority
   PORT=8080
   LOG_LEVEL=info

Run the server

npm run dev

The server listens on http://localhost:8080 and exposes:

• /healthz — Health check endpoint (returns 200 {status: 'ok'} if MongoDB is reachable)

• /mcp — MCP HTTP transport endpoint (accepts POST requests with MCP JSON-RPC messages)

Seed sample data

Before testing the tools, populate the database with sample vendors:

MONGODB_URI=mongodb+srv://<your-credentials>@<cluster>/<db> npm run seed

Important: Only run the seed script against a test or development database that you control. The script clears any existing vendors collection and replaces it with sample data.

Test the tools

Use an MCP client (such as the Claude Code CLI with MCP support) to call the tools via POST /mcp.

Or, manually test with curl:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_expiring_vendors",
      "arguments": { "daysAhead": 30 }
    }
  }'

Architecture

Project Structure

src/
├── server.ts                  # Express app, MCP server setup, HTTP endpoints
├── db.ts                      # MongoDB connection, query helpers
├── logger.ts                  # Structured JSON logging (pino)
├── types.ts                   # TypeScript types and serialization
└── tools/
    ├── listExpiringVendors.ts
    ├── getVendor.ts
    ├── updateAccreditationStatus.ts
    └── searchVendors.ts

scripts/
└── seed.ts                    # Manual script to initialize sample data

Dockerfile                     # Multi-stage build for Cloud Run

Data Model

The vendors collection stores vendor documents with embedded audit logs:

{
  vendorId: string;              // Stable external ID (UUID)
  vendorName: string;
  category: string;
  contactEmail: string;
  accreditationStatus: 'Active' | 'Expired' | 'Suspended';
  accreditationExpiryDate: Date;
  auditLog: Array<{              // Embedded audit history
    timestamp: Date;
    previousStatus: string;
    newStatus: string;
    reason: string;
  }>;
  createdAt: Date;
  updatedAt: Date;
}

Indexes

Created automatically by the seed script:

• { vendorId: 1 } (unique) — for lookups and updates

• { accreditationStatus: 1, accreditationExpiryDate: 1 } — for expiring-vendors queries

• { category: 1 } — for category filtering and discovery

Logging

Uses structured JSON logging via pino. Sensitive data is never logged — logs only include:

• Non-sensitive identifiers: vendorId, tool name, operation, status codes

• Metrics: durationMs, resultCount, queryLength

• Errors: error type (never the full message if it could contain credentials)

Logs never include: full vendor records, contact emails, category values from queries, or the reason field (free text could contain PII).

Security Notes

• No request-level authentication is implemented yet. Cloud Run IAM (via --no-allow-unauthenticated) is the only perimeter. See Follow-up: Authentication below.

• Credentials are never hardcoded. The MONGODB_URI must be supplied via environment variables, backed by Google Secret Manager in production.

• Input validation uses zod on every tool parameter.

• Regex queries are escaped to prevent ReDoS attacks.

Cloud Run Deployment

Prerequisites

• gcloud CLI installed and authenticated

• A GCP project with Cloud Run and Artifact Registry enabled

• A MongoDB Atlas cluster (or another reachable MongoDB instance)

Step 1: Store credentials in Secret Manager

gcloud secrets create MONGODB_URI --replication-policy="automatic"
printf '%s' "$MONGODB_URI" | gcloud secrets versions add MONGODB_URI --data-file=-

Step 2: Build and push the Docker image

# Configure Docker authentication (one-time)
gcloud auth configure-docker us-central1-docker.pkg.dev

# Build the image
docker build -t us-central1-docker.pkg.dev/PROJECT_ID/vendor-accreditation/mcp-server:latest .

# Push to Artifact Registry
docker push us-central1-docker.pkg.dev/PROJECT_ID/vendor-accreditation/mcp-server:latest

Replace PROJECT_ID with your GCP project ID.

Step 3: Deploy to Cloud Run

gcloud run deploy vendor-accreditation-mcp \
  --image=us-central1-docker.pkg.dev/PROJECT_ID/vendor-accreditation/mcp-server:latest \
  --region=us-central1 \
  --platform=managed \
  --no-allow-unauthenticated \
  --port=8080 \
  --memory=512Mi \
  --min-instances=0 \
  --max-instances=5 \
  --set-secrets=MONGODB_URI=MONGODB_URI:latest \
  --set-env-vars=LOG_LEVEL=info

The --no-allow-unauthenticated flag ensures that only principals with roles/run.invoker can invoke the service. This is the current security perimeter until app-level auth is added.

Step 4: Test the deployment

gcloud run services describe vendor-accreditation-mcp --region=us-central1

# Get the service URL and test the health endpoint
curl https://vendor-accreditation-mcp-RANDOM.run.app/healthz

Optional: Private networking

If your MongoDB Atlas cluster requires private network access instead of a public IP allowlist:

1. Create a Serverless VPC Access connector:

   gcloud compute networks vpc-access connectors create vendor-mcp-connector \
     --region=us-central1 \
     --range=10.8.0.0/28

2. Set up Atlas Network Peering or PrivateLink between GCP and MongoDB Atlas.

3. Deploy with the connector:

   gcloud run deploy vendor-accreditation-mcp \
     ... \
     --vpc-connector=vendor-mcp-connector \
     ...

Build & Test

# Type checking
npm run typecheck

# Build the project
npm run build

# Run the compiled server
npm start

Follow-up: Authentication

⚠️ No request-level authentication is implemented yet.

Currently, Cloud Run IAM (via --no-allow-unauthenticated) is the only perimeter; the service is not callable without an explicit roles/run.invoker grant. This is sufficient for internal procurement tools but inadequate for public APIs or cross-organizational integrations.

Before any of the following, add bearer-token or IAM-identity validation in src/server.ts at the marked // TODO(auth) comment:

• Granting allUsers invoker access

• Allowing external vendors to call the service directly

• Consuming this MCP server via a public-facing LLM or agent

Suggested approaches:

• Cloud Run IAM check: Validate the Authorization: Bearer token against Cloud Run's default service account identity.

• Shared bearer token: Store a secret API key in Secret Manager and validate the request's Authorization header.

• Mutual TLS: Use Cloud Run's mTLS support for service-to-service calls.

See src/server.ts for the exact location and Cloud Run documentation for implementation patterns.

License

MIT