Trafft MCP Read-Only

Project status — remote-access upgrade in review (August 2026)

The hardened July 2026 read-only implementation remains the verified baseline. Development was reopened on August 9, 2026 to add an authenticated remote MCP transport so the same validated tool surface can be hosted for remote MCP clients.

Trafft's current public documentation describes a broader API surface than was available during the July validation. This branch does not infer or enable write tools from high-level documentation alone. Stable tools remain read-only until exact endpoint, request-body, cancellation, and failure semantics are verified against Trafft's current official contract.

A hardened Model Context Protocol server for inspecting Trafft booking data without exposing mutation tools. It supports both local stdio and bearer-protected remote Streamable HTTP transports.

This repository is a clean derivative of mjmirza/trafft-mcp at commit c8793116e564a6c84d4e727ee0d4c7f24aef45ff. It retains the upstream MIT terms and documents material changes in UPSTREAM.md and NOTICE.

Stable tool surface

• list_services

• get_service

• find_services_by_name

• list_employees

• get_employee

• list_locations

• get_location

• list_appointments

• list_customers

• get_customer

• find_duplicate_customers

• get_available_times

• compare_services_to_expected

get_available_times accepts one service and one date, then maps them to Trafft's documented calendar_start_date, calendar_end_date, and service query parameters. Optional employee, location, and additional-guest inputs are mapped to the published API names.

No create, update, cancel, reschedule, pricing-write, webhook-write, booking, coupon, or delete tool is compiled into the stable tool surface.

Six experimental read-only probes—webhooks, notifications, working hours, Special Days, Days Off, and settings—remain disabled unless TRAFFT_ENABLE_EXPERIMENTAL_READS=true. They should not be enabled without fresh verification against Trafft's current official API.

Related MCP server: finance-reconcile-mcp

Local stdio transport

npm ci --ignore-scripts
npm run build
npm run start:stdio

The original stdio transport is preserved for local MCP clients.

Remote Streamable HTTP transport

The remote server exposes:

• GET /healthz — non-sensitive health response

• POST /mcp — stateless MCP endpoint

• bearer authentication on every /mcp request

• bounded JSON request bodies

• the same Trafft origin allowlist, path confinement, redirect refusal, response limits, sanitized errors, and audit logging used by the stdio build

Configure the normal TRAFFT_* values plus a separate MCP_ACCESS_TOKEN of at least 32 characters. The MCP access token is not a Trafft API credential.

npm ci --ignore-scripts
npm run build
MCP_ACCESS_TOKEN='use-a-secure-secret-store' npm run start:remote

Local binding defaults to 127.0.0.1:3000. Hosted containers should set MCP_BIND_HOST=0.0.0.0 behind an HTTPS ingress or reverse proxy. The included Dockerfile does this automatically for the container runtime.

Remote client configuration

A remote MCP client should target the hosted HTTPS endpoint ending in /mcp and send:

Authorization: Bearer <MCP_ACCESS_TOKEN>

Never put TRAFFT_CLIENT_ID or TRAFFT_CLIENT_SECRET into the MCP client configuration. Those credentials belong only in the server-side secret store.

Container deployment

Build and run the included production container with all secrets injected at runtime. Do not bake .env files, API credentials, or MCP access tokens into the image.

The container exposes port 3000, starts build/remote.js, and keeps audit storage writable for the non-root Node user. Production ingress must provide HTTPS.

Security architecture

• Local stdio and remote Streamable HTTP MCP transports

• Separate bearer secret for remote MCP access

• HTTPS-only Trafft origin

• Exact Trafft hostname allowlist

• API-path confinement and encoded-traversal rejection

• Redirect refusal

• GET-only Trafft REST policy, except the authentication POST

• In-memory Trafft bearer token

• Sanitized errors and request identifiers

• Bounded safe-GET retries

• Streaming response-size enforcement

• Bounded remote request bodies

• Valid-JSON MCP response limits

• Privacy-minimized JSONL operation log

• No deep/write audit mode

See SECURITY.md for the verified baseline guarantees and limitations.

Development gate

npm ci --ignore-scripts
npm run check
npm audit --audit-level=high
npm pack --dry-run

The mock security suite does not call Trafft and does not require credentials.

Secret handling

Never commit credentials or paste them into chat, issues, screenshots, fixtures, or shell history. Use an OS secret store or approved private runtime injection.

Historical API boundary

The July 2026 implementation intentionally compiled only read operations after Trafft Support described a much narrower mutation surface at that time. Those findings remain part of the project history, but should not be treated as a claim about Trafft's present-day API.

Current write support will be considered only from exact, current, official Trafft request contracts and controlled validation. Undocumented dashboard endpoints are out of scope.

Questions and comments

Use the standing project-status issue for general questions and compatibility discussion. Security concerns should be reported privately through GitHub Security Advisories.

Independence

This project is not affiliated with, endorsed by, or sponsored by Trafft. Trafft is a trademark of its respective owner.