mock-mcp-local

Minimal local HTTP MCP mock server for development integration.

Why this exists

• fast local connector testing

• zero dependencies and setup

• deterministic tool responses for dev and demos

Related MCP server: Mock MCP Server

Requirements

• Node.js 18+

Run

npm start

Defaults:

• host: 0.0.0.0

• port: 8787

• MCP endpoint: http://localhost:8787/mcp

• OAuth token endpoint: http://localhost:8787/oauth/token

Optional overrides:

HOST=0.0.0.0 PORT=8787 npm start

Code structure

• server.mjs: HTTP bootstrap and route wiring

• src/config.mjs: environment-driven config and client loading

• src/http.mjs: shared HTTP/response/body parsing helpers

• src/auth.mjs: token issuing + Bearer validation

• src/tools.mjs: mock tool catalog + implementations

• src/rpc.mjs: MCP JSON-RPC dispatcher + cancellation handling

Health check

GET /health

Example:

curl http://127.0.0.1:8787/health

MCP methods supported

• initialize

• notifications/initialized

• tools/list

• tools/call

• $/cancelRequest

• notifications/cancelled

• resources/list (returns empty)

• prompts/list (returns empty)

Auth flow

POST /mcp requires Authorization: Bearer <access_token>.

Get token first (client credentials):

curl -X POST http://localhost:8787/oauth/token ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "grant_type=client_credentials&client_id=demo-client&client_secret=demo-secret&scope=crm.read%20crm.write%20crm.enrich"

Tools exposed

1. crm.search_contacts

   • input: { "query": "alice" }

2. crm.create_deal

   • input: { "title": "Pilot", "amount": 25000, "contactId": "c_1001" }

Quick test payloads

Initialize:

curl -X POST http://127.0.0.1:8787/mcp ^
  -H "Authorization: Bearer <access_token>" ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{}}"

List tools:

curl -X POST http://127.0.0.1:8787/mcp ^
  -H "Authorization: Bearer <access_token>" ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}"

Call crm.search_contacts:

curl -X POST http://127.0.0.1:8787/mcp ^
  -H "Authorization: Bearer <access_token>" ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"crm.search_contacts\",\"arguments\":{\"query\":\"alice\"}}}"

Cancel a running request:

curl -X POST http://127.0.0.1:8787/mcp ^
  -H "Authorization: Bearer <access_token>" ^
  -H "Content-Type: application/json" ^
  -d "{\"jsonrpc\":\"2.0\",\"id\":99,\"method\":\"$/cancelRequest\",\"params\":{\"requestId\":3,\"reason\":\"user aborted\"}}"

Connector UI values (tfGPT Desktop)

• type: mcp

• transport: http

• server_url: http://127.0.0.1:8787/mcp