Instaclean MCP

Remote Model Context Protocol server for Instaclean. It gives AI clients such as ChatGPT, Claude, Cursor, and internal operations agents a standardized tool interface while keeping Mithril as the source of truth for authorization, pricing, booking, availability, dispatch, and audit rules.

Architecture

ChatGPT / Claude / Cursor / Ops Agent
                 |
                 | MCP over HTTP
                 v
        instaclean-mcp (/mcp)
                 |
                 | authenticated HTTP/JSON
                 v
       api.tryinstaclean.com
                 |
                 v
              Mithril

The MCP server does not connect directly to PostgreSQL and does not duplicate Mithril business logic.

Related MCP server: ParcelPilot MCP Server

Tools

Read

• search_customers - admin customer search by name, email, or phone

• list_dispatch_requests - admin urgent-help/replacement queue

• list_my_service_requests - current customer's urgent-help/replacement requests

• list_booking_services - active Direct booking services

• list_available_workers - verified professionals eligible for a service

• get_booking - current customer's booking details

Write

• create_admin_booking - admin-assisted booking with explicit customer consent

• create_urgent_help_request - non-medical urgent household help

• request_replacement - replacement request for an owned booking

• assign_worker - vetted worker assignment through Mithril's assignment endpoint

• update_service_request - triage/matching/resolve/cancel transitions

Payments, refunds, payouts, pricing mutation, account deletion, and verification mutation are intentionally not exposed in the initial MCP surface.

Authentication

The server supports two modes.

passthrough (default)

The MCP request must contain:

Authorization: Bearer <mithril-access-token>

The token is forwarded to Mithril. Mithril validates the user and enforces customer/admin authorization. This is the preferred model for user-scoped MCP connections.

service

Use this only for an internal Instaclean operations agent with a dedicated active admin account. The caller authenticates to the MCP server with MCP_API_KEY; the MCP server then calls Mithril using the configured Direct gateway token and actor user ID.

Required environment variables:

AUTH_MODE=service
MCP_API_KEY=...
MITHRIL_DIRECT_TOKEN=...
MITHRIL_ACTOR_USER_ID=...

Do not use a customer account as the service actor and do not put these values in source control.

Origin protection

MCP clients normally make server-to-server requests without an Origin header. If an Origin header is present, the server requires it to match ALLOWED_ORIGINS. This protects the HTTP MCP endpoint against browser-based DNS-rebinding attacks.

Development

Requires Node.js 22+.

cp .env.example .env
npm install
npm run check
npm run dev

The local endpoints are:

GET/POST http://127.0.0.1:3000/mcp
GET      http://127.0.0.1:3000/health

The MCP SDK's HTTP handler also retains stateless compatibility with 2025-era clients while supporting the current 2026 protocol.

Example Cursor configuration

For service mode or development clients that support static headers:

{
  "mcpServers": {
    "instaclean": {
      "type": "http",
      "url": "https://mcp.tryinstaclean.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:INSTACLEAN_MCP_TOKEN}"
      }
    }
  }
}

Never commit the token to a Cursor configuration checked into the repository.

Deployment

The included Dockerfile is suitable for Fly.io or another container host. Production should expose only HTTPS externally.

For Fly.io, create the app and set secrets rather than editing fly.toml with credentials:

fly secrets set \
  MITHRIL_API_URL=https://api.tryinstaclean.com \
  AUTH_MODE=service \
  MCP_API_KEY=... \
  MITHRIL_DIRECT_TOKEN=... \
  MITHRIL_ACTOR_USER_ID=...

Then point mcp.tryinstaclean.com to the deployed service.

Next security milestone: OAuth

The initial server deliberately supports bearer passthrough and a service-agent mode without implementing a second identity system. Before broadly connecting third-party users, add OAuth 2.1 / MCP Protected Resource Metadata so ChatGPT, Claude, and other clients can obtain scoped Mithril tokens interactively instead of receiving manually copied access tokens.

Mithril remains responsible for role checks and business invariants even after OAuth is added.