David/MEGAINFRA-WEBAPP
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
MEGAINFRA-WEBAPP/docs/setup/remote-purchasing-mcp.md

11 KiB
Raw Permalink Blame History

MEGA remote MCP: connection and deployment guide

Prepared 5 October 2026. The endpoint is implemented on branch codex/remote-purchasing-mcp; production activation requires deployment of this branch and the additive MCP schema. The production URL is a target until its external handshake passes.

Connection

Setting Value
Remote URL https://mega.dash.apphub.co.za/api/mcp
Transport MCP Streamable HTTP, stateless JSON responses
Authentication Authorization: Bearer <your dedicated MCP key>
Hosting Existing Next.js app, existing Coolify container/domain/HTTPS
Server credentials Existing PocketBase admin credentials, kept server-side
Local stdio Preserved, read-only by default
Delete access No business delete/removal tools; record/batch deletion and source replacement rejected
Stock scope Received and outstanding PO quantities; no physical warehouse/site inventory ledger

Separate credentials were generated in the ignored .env.mcp.local file in the feature worktree. It contains MEGA_MCP_CODEX_TOKEN, MEGA_MCP_HERMES_TOKEN, MEGA_MCP_COWORK_TOKEN, MEGA_MCP_READER_TOKEN, MEGA_MCP_SCHEDULER_TOKEN and the server's MCP_CLIENTS_JSON. File permissions are 0600. Actual values are deliberately kept out of this shareable document and Git. The first three grant all-site read/write owner access; reader grants reads only; scheduler grants job processing only. Each can be revoked by removing its entry from the server JSON and redeploying/reloading the app.

The raw tokens belong in each client's secure configuration. Coolify needs only the credential IDs, permissions and SHA-256 hashes in MCP_CLIENTS_JSON, plus the existing server/PocketBase/provider environment. Do not paste PocketBase credentials or the n8n ingest secret into an MCP client. Generate another client credential with node scripts/generate-mcp-key.mjs, which prints a fresh token and its matching hash once.

Clients and cloud access

Any cloud agent that supports Streamable HTTP plus bearer headers can use this URL once deployed and reachable from its runtime. The MCP server runs on Coolify, so its availability is independent of the owner's Mac. The client or scheduled agent still needs its own running execution environment and securely available key.

Codex supports remote URLs and bearer_token_env_var. Use mega-mcp.remote.codex.toml, setting MEGA_MCP_TOKEN securely in the runtime that makes the connection. A desktop scheduled task depends on its configured host. For Work Cloud or another cloud executor, verify that the selected runtime receives the remote MCP config and bearer secret; local Codex settings alone do not prove that the cloud agent can connect. See official Codex MCP settings.

Hermes supports URL/header configuration and secret environment references. Use mega-mcp.hermes.yaml; place the Hermes token in its active secret scope as MEGA_MCP_TOKEN. See official Hermes MCP reference.

For Claude Cowork/custom remote connectors, use the same URL and a fixed Authorization request header with the Cowork token. Current Claude documentation describes this request-header authentication; remote calls originate from Anthropic infrastructure and need public reachability. The actual user's Cowork connection has not been tested. See official remote connector setup.

For clients with mcpServers JSON configuration, mega-mcp.remote.json supplies the shape. Replace the placeholder in a local secret-managed copy; configuration support varies by client. OAuth is not implemented in this fixed-credential release.

Tools and workflow

The original 27 read tools remain available. Purchasing tools add bounded record/detail reads, reconciliation, source/proof downloads and operation status. A read key discovers only read tools; a write key also discovers the named purchasing mutations. Tool annotations aid clients, while permission checks and the database boundary enforce access.

Write tools cover manual PO creation/header editing/line editing/verification; PO and DN source uploads; candidate creation/corrections/grouping; supplier guidance; supplier/PO/item resolution; candidate preview processing; durable batch processing; explicit line receipt posting; permitted legacy receipt correction; and delivery verification. There are no generic database, SQL, Ask-action, account-management or arbitrary HTTP tools.

Every write requires a fresh UUID operationId. Retry the same operation with the same arguments after a lost connection: the journal returns its saved committed result. Reusing the ID for different arguments fails. An uncertain operation needs reconciliation rather than a blind duplicate write. get_mcp_operation reads only the credential's operations. Posted per-line receipts are immutable, as in the app; the legacy correction tool refuses them.

Suggested sequence:

  1. Read the PO and its lines; inspect received/outstanding quantities.
  2. Upload one source at a time, using stable operation IDs. Delivery uploads may add to an existing batch. PDFs/images are bounded to 20 MiB and PDFs to 100 pages.
  3. Queue process_delivery_batch; poll get_mcp_operation. Grouping/review may still need operator decisions.
  4. Correct permitted candidate fields and match supplier, PO and individual lines. Matching alone books nothing.
  5. Call process_delivery_candidate for the current comparison preview.
  6. Call post_delivery_line with the preview hash, source-line IDs, allocation index and confirmation.confirmed=true. Review changes/excess require the existing confirmation reason and acknowledgment fields.
  7. Re-read PO detail/reconciliation to verify received/outstanding quantities and retrieve proof PDFs.

Some broad regroupings exceed the 50-request transactional batch budget. They fail before any business commit instead of silently splitting an operation. Retained source files and superseded candidates are not deleted. Failed or duplicate PO extraction retains MCP-uploaded original documents.

get_document_download returns filename, MIME, size and an app URL requiring the same bearer header. A link alone grants no access. read_document returns up to 2 MiB per base64 segment with offset/nextOffset for larger documents. Candidate proof PDFs use saved source page order. There are no returned PocketBase admin/file tokens or arbitrary caller-selected file paths.

Coolify environment and deployment

Use mega-mcp.env.example for variable names. Set:

  • MCP_PUBLIC_URL=https://mega.dash.apphub.co.za/api/mcp.
  • MCP_ALLOWED_ORIGINS=https://mega.dash.apphub.co.za or a comma-separated list of approved browser origins. Server clients may omit Origin.
  • MCP_CLIENTS_JSON with real generated hashes and selected permissions. Invalid/missing config returns 503 on MCP routes while dashboard health remains available.
  • Existing NEXT_PUBLIC_POCKETBASE_URL, server admin email/password, optional preset admin token and processing provider keys. The dedicated purchasing client refreshes an expired preset token at initialization.
  • MCP_JOB_SCHEDULE_CONFIGURED=true only after the processing schedule actually exists.

Before deployment, run the additive schema migration against an isolated/staging PocketBase database:

node --env-file=.env.staging.local scripts/migrations/2026-10-05-add-mcp-operations.mjs
node --env-file=.env.staging.local scripts/migrations/2026-10-05-add-mcp-operations.mjs --apply

The first command is a read-only dry run. The second creates/extends private operations, jobs and resource lock collections, backs up existing schema before modification, and verifies fields/indexes. It preserves existing business data and rules. Existing DN staged-ingestion/line-posting schemas and PocketBase transactional batch support are also required. Writes fail closed when required schema is absent. Review the schema result before applying to production.

The 5 October read-only dry run against the currently configured PocketBase found all three MCP collections absent. No schema changes were applied. Apply the additive migration to the database used by the updated deployment before enabling write credentials.

Deploy the existing app image; do not add a second container, DNS entry or public port. Existing /api/health remains the liveness endpoint. The MCP POST handshake is its separate readiness check. The updated Docker exclusions cover local credentials/agent state. The Docker image itself was not built because the Docker daemon was unavailable at unix:///Volumes/KIOXIA/.docker/run/docker.sock; the standalone Next.js build succeeded.

Configure an external scheduler, such as the existing n8n instance, to call:

POST https://mega.dash.apphub.co.za/api/mcp/jobs/tick
Authorization: Bearer <scheduler credential>

No body is needed. Run once per minute. One request claims one job; PocketBase persists status, retries and leases. Reads and browser write credentials cannot tick jobs. Processing retries at most three times with increasing delays. Deadlines are checked between source/page/group stages; an in-flight provider request may finish after the cooperative deadline, so configure the Coolify proxy timeout to 600 seconds. Cached reads allow later attempts to continue. Do not invoke the old global DN tick with an MCP key or reuse the ingest secret. No background promise continues invisibly after a response.

Verification and current limits

Final local validation on 5 October 2026: 2,256 tests passed across 248 files, 4 migration/key script tests passed, TypeScript and relevant ESLint passed, and npm run build produced the Next.js standalone production build. Its HTTP MCP endpoint then passed 13/13 local checks. A read credential discovered 35 read tools and completed four live reads against the configured PocketBase; a write credential discovered 53 total tools, including 18 writes, without invoking a mutation. Invalid bearer, untrusted Origin and unauthenticated document requests returned 401, 403 and 401. Details are in remote-mcp-check-results.json.

Read-only HTTP checks can run against the local app or deployed endpoint:

node scripts/check-connections.mjs --mcp-url http://127.0.0.1:6005/api/mcp http://127.0.0.1:6005

The checker uses MEGA_MCP_TOKEN or the generated reader credential and prints metadata, never business records or keys. A production HTTP smoke requires the production deployment and a configured reader key.

scripts/mcp-staging-smoke.mjs creates/edits/verifies a fixture PO and refuses the known production origin. It requires MEGA_MCP_STAGING_URL, MEGA_MCP_TOKEN, MEGA_MCP_STAGING_SITE and MEGA_MCP_STAGING_SUPPLIER. Full source-download/matching/posting exercise additionally requires prepared staged evidence/model configuration. Database fixture tests do not establish that a real deployment's PocketBase schema or client account works.

Production deployment, external MCP initialization, a real staging mutation/PDF/posting exercise and personal Codex/Hermes/Cowork connections remain to be verified. No production business writes or schema changes were performed during implementation. Physical stock-on-hand is outside this release.