MCP Server Tests

Vitest test suite for APIMatic's MCP (Model Context Protocol) server. Tests connection, tool discovery, tool invocations, schema snapshots, and ContextMatic training data health.

Test Files

File	What It Tests
tests/connection.test.ts	Connects to MCP server, verifies 4 tools are listed, validates each tool has a name/description/schema
tests/tool-schemas.test.ts	Snapshot test — compares live tool schemas against saved baseline
tests/tool-calls.test.ts	Calls each tool (ask, model_search, endpoint_search, update_activity) with valid and edge-case inputs
tests/contextmatic-health-check.test.ts	Fetches the API catalog for 7 languages via fetch_api and verifies training data exists for each entry
tests/discover.ts	Utility script — prints all available tools as JSON (not a test)

Setup

1. Install dependencies

   npm install

2. Configure environment

   Copy .env.example to .env and fill in your values:

   cp .env.example .env

   Variable	Used by	Description
   MCP_SERVER_URL	mcp-server-tests.yml, connection/tool-calls/tool-schemas tests	Full MCP server endpoint URL including language path
   CONTEXTMATIC_MCP_URL	contextmatic-health-check.test.ts	ContextMatic plugins MCP endpoint
   TRAININGDATA_BASE_URL	contextmatic-health-check.test.ts	Base URL for the training data health check API

Running Tests

# All tests except contextmatic health check
npx vitest run tests --exclude tests/contextmatic-health-check.test.ts

# ContextMatic health check only
npx vitest run tests/contextmatic-health-check.test.ts

# All tests
npx vitest run tests

# View results in browser
npx vitest run tests --reporter=html

HTML report is written to mcp-server-tests-report/index.html.

How Authentication Works

The MCP server uses OAuth 2.0 client credentials. tests/helpers/client.ts handles this automatically:

1. Fetches /.well-known/oauth-protected-resource from the server origin to discover the token endpoint
2. Exchanges client credentials for a Bearer token
3. Attaches the token to all MCP transport requests

No API key or client secret is needed in .env — the server's OAuth metadata is resolved at runtime from the URL itself.

Updating Snapshots

If tool schemas change intentionally, update the snapshot:

npx vitest run tests/tool-schemas.test.ts --update-snapshots

CI

Two workflows in .github/workflows/:

Workflow	Trigger	Tests run
mcp-server-tests.yml	Manual dispatch (dev/prod)	All except contextmatic health check
contextmatic-health-check.yml	Manual + daily at 4 PM PKT	contextmatic-health-check.test.ts only

Required GitHub secrets for mcp-server-tests.yml:

Secret	Description
MCP_SERVER_URL_DEV	Dev MCP server URL
MCP_SERVER_URL_PROD	Prod MCP server URL

The contextmatic health check workflow also requires SLACK_BOT_TOKEN for failure notifications.