Parcel MCP Server

A mock MCP (Model Context Protocol) server that simulates small parcel and package operations. Designed for use with AI agents, it exposes 12 tools covering the common actions a driver or package processing centre would need to remedy recipient issues.

Live Server

Hosted on Railway — always on, no setup required.

Health check	https://parcel-mcp-server-production.up.railway.app/health
MCP endpoint	https://parcel-mcp-server-production.up.railway.app/mcp
OAuth token URL	https://parcel-mcp-server-production.up.railway.app/oauth/token

Salesforce Agentforce Registry Connection

To register this server in the Salesforce Agentforce Registry, use the following settings:

Field	Value
MCP Server Name	Parcel MCP Server
Server URL	https://parcel-mcp-server-production.up.railway.app/mcp
Authentication Method	OAuth 2.0
Identity Provider URL	https://parcel-mcp-server-production.up.railway.app/oauth/token
Scope	read
Client ID	any value
Client Secret	any value

The OAuth endpoint is a mock — it accepts any client ID and secret and returns a valid bearer token.

Tools

Tool	Description
track_package	Look up status, location history, and delivery details by tracking number
list_packages_for_driver	List all packages assigned to a driver with status and recipient info
update_delivery_status	Log delivery attempts, exceptions, or completions
correct_delivery_address	Submit a corrected address for an invalid or undeliverable package
schedule_redelivery	Book a redelivery with preferred date and time window
request_hold_for_pickup	Hold a package at the nearest facility for recipient pickup
initiate_return_to_sender	Mark a package for return with a reason code
update_recipient_contact	Update phone or email for delivery notifications
report_damaged_package	File a damage claim with severity level
get_facility_info	Get hours, address, and accessibility info for the holding facility
send_delivery_notification	Send SMS or email notification to the recipient
get_route_summary	Get a driver's route stats — delivered, pending, exceptions

Mock Data

Four packages are pre-loaded covering the main exception scenarios:

Tracking #	Status	Scenario
1Z999AA10123456784	OUT_FOR_DELIVERY	Normal delivery in progress — Jane Smith, Denver CO
1Z999AA10234567895	DELIVERY_EXCEPTION	Address not found, buzzer issue — Bob Johnson, Denver CO
1Z999AA10345678906	HELD_AT_FACILITY	Max attempts reached, awaiting pickup — Maria Garcia, Aurora CO
1Z999AA10456789017	PENDING_ADDRESS_CORRECTION	Invalid ZIP code — Tom Lee, Denver CO

Two drivers are also pre-loaded: DRV-101 (Route A — first two packages) and DRV-102 (Route B — last two packages).

Architecture

The diagram below shows the full request flow from Agentforce through the Salesforce Apex invocable action to this MCP server.

┌─────────────────┐     invoke action      ┌──────────────────────┐
│   Agentforce    │ ─────────────────────► │  TrackParcelAction   │
│  Agent Studio   │ ◄─────────────────────  │  (@InvocableMethod)  │
└─────────────────┘     response           └──────────┬───────────┘
                                                       │
                              POST /oauth/token        │  POST /mcp
                         ┌─────────────────────────────┤
                         ▼                             ▼
               ┌──────────────────┐       ┌───────────────────────┐
               │   OAuth Server   │       │   Parcel MCP Server   │
               │ client_creds JWT │       │   JSON-RPC 2.0        │
               └──────────────────┘       │   tools/call          │
                                          └───────────┬───────────┘
                                                      │
                                          ┌───────────▼───────────┐
                                          │   Tool Handler        │
                                          │  track_package etc.   │
                                          └───────────────────────┘

An interactive HTML visualization (mcp-visualization.html) is included in the repo — open it in a browser to animate the full request/response flow, explore all 12 tools, and inspect parsed and raw JSON-RPC responses.

Running Locally

No npm install required — the server uses only Node.js built-ins.

node server.js
# Server runs on http://localhost:3333

Or use the included launcher which starts the server and an ngrok tunnel together:

bash launch.command

The launcher prints your public ngrok URL and the Salesforce connection settings automatically.

Redeploying to Railway

Any changes to server.js can be redeployed with:

railway up

Make sure you have the Railway CLI installed and are logged in (railway login).