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: mcp-hello-world

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:

• alice@example.test / alice-password with crm.read crm.write crm.enrich

• bob@example.test / 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\":\"alice@example.test\",\"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