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

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