Mock

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
• OAuth authorize endpoint: http://localhost:8787/oauth/authorize
• Direct email/password login endpoint: http://localhost:8787/oauth/login

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>.

Default OAuth client:

• client_id: demo-client
• client_secret: demo-secret
• scopes: crm.read crm.write crm.enrich

Default mock users:

• [email protected] / alice-password with crm.read crm.write crm.enrich
• [email protected] / bob-password with crm.read

Client credentials token

Use this for machine-to-machine testing:

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"

Mock OAuth authorization code login

Open the authorize URL in a browser. The mock server renders a login page, accepts one of the default mock users, then redirects to redirect_uri with a temporary code.

http://localhost:8787/oauth/authorize?response_type=code&client_id=demo-client&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&scope=crm.read%20crm.write&state=demo-state

Exchange the returned code for an access token:

curl -X POST http://localhost:8787/oauth/token ^
  -H "Content-Type: application/x-www-form-urlencoded" ^
  -d "grant_type=authorization_code&client_id=demo-client&client_secret=demo-secret&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&code=<code>"

Direct mock email/password login

Use this when you want a token response directly from the mock server without browser redirects:

curl -X POST http://localhost:8787/oauth/login ^
  -H "Content-Type: application/json" ^
  -d "{\"client_id\":\"demo-client\",\"email\":\"[email protected]\",\"password\":\"alice-password\",\"scope\":\"crm.read crm.write\"}"

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