Zid AI Agent Skill and MCP: a verified integration workflow

Zid's official developer documentation now describes two complementary tools for AI-assisted integration work: the open-source Zid AI Agent Skill and the Zid documentation MCP server. The skill supplies reusable Zid-specific rules and architectural guidance; MCP gives a compatible coding agent a way to retrieve documentation context. Neither tool turns generated code into verified API behavior by itself.

That distinction matters for commerce systems. A plausible but wrong endpoint can fail visibly, while a misplaced merchant token can cross a tenant boundary. An overly aggressive retry can duplicate a mutation, and an unbounded agent can exhaust a store's API budget. The useful architecture is therefore not “ask the agent to build the integration.” It is a controlled workflow in which the agent retrieves, proposes and tests while the application contract remains authoritative.

This article is a practical explainer based on Zid's official documentation, not a claim about a new release in the last 48 hours. The AI Agent Skill page was modified on 21 July 2026, the MCP setup page on 30 July 2026, and the referenced live documentation was verified on 2 October 2026.

Start with a task contract, not a broad prompt

Before the agent reads documentation or writes code, give it a bounded integration contract. State the app type, merchant scope, exact business action, allowed side effects, language and framework, and the evidence that will prove success. “Integrate Zid orders” is too broad. “Read changed orders for one installed store, normalize them into this schema and never change remote state” creates an enforceable boundary.

The contract should list unknowns explicitly. If the HTTP method, route, scope, header or supported value is not in the current documentation, the agent must stop and retrieve it. It must not infer an endpoint from naming conventions or from another commerce platform. Zid's skill documentation makes the same source-of-truth rule clear: method, URL, scopes, authentication headers, parameters, request body, response schema, rate-limit behavior and errors should be checked against the live endpoint documentation before implementation.

A compact task file can make this repeatable:

integration: zid
store_scope: one installed merchant
operation: read_changed_orders
side_effects: forbidden
required_evidence:
  - official endpoint URL and method
  - required scopes and both auth headers
  - sanitized success and error fixtures
  - contract tests for 401, 403, 422 and 429
unknown_behavior: stop_and_report

Keep the prompt and this contract in version control beside the adapter. When the generated implementation changes, reviewers can compare the code with the intended operation instead of reviewing an unbounded conversation.

Use the skill for rules and MCP for current evidence

The two tools solve different problems. The AI Agent Skill is a stable instruction layer: it explains Zid's OAuth pattern, multi-tenant credential isolation, error handling, rate limits and troubleshooting workflow. The MCP server is a retrieval layer that can provide documentation context inside compatible tools. The skill tells the agent how to reason; MCP helps it find what the current docs say.

Treat retrieved text as evidence, not executable authority. The agent should cite the exact documentation page used for every remote operation and record when it was verified. If MCP returns no matching endpoint, the correct output is a documented gap—not an invented route. If the skill and live documentation disagree, Zid says the live documentation wins.

Create a small evidence manifest during planning: operation name, source URL, verification date, HTTP method, path, scopes, headers, pagination or rate-limit notes and unresolved questions. That manifest can feed code review and later drift checks. It also prevents the common failure where an agent retrieves the correct page but writes code from its prior model knowledge.

Retrieval should be narrow. Load the OAuth reference for installation or refresh work, the endpoint page for the requested resource and the rate-limit page for queue behavior. Pulling the entire documentation tree into context increases noise and makes contradictions harder to detect. Progressive disclosure is more reliable than a large undocumented context dump.

Model Zid credentials as a tenant boundary

The Zid authorization documentation describes an authorization-code flow and generally requires two distinct values on Merchant API requests: `Authorization` and `X-Manager-Token`. The authorization token grants API access, while the manager token identifies access to a particular store. The page also states that the backend must hold the client secret and that merchant uninstall invalidates the tokens.

Do not flatten those values into one generic `api_token` field. Store an encrypted credential envelope keyed by the internal tenant and the immutable Zid installation or store identity. Keep token type, encrypted values, expiry, scopes, installation state and last verified time separate. A worker must resolve credentials from the job's tenant context; callers must never submit an arbitrary store token with a job.

Use database constraints so one installation cannot be attached silently to two tenants. Include tenant and installation identifiers in cache keys, queue payloads, rate-limit buckets and idempotency records. Log credential references, not credential values. On uninstall, mark the installation revoked before scheduling cleanup so no worker can continue using a cached credential.

Token refresh needs single-flight control. When multiple workers notice expiry, one worker refreshes while the others wait for the credential version to advance. Replace both access values atomically and keep a short audit record of the version transition without storing plaintext. If the outcome of a refresh request is unknown, retrieve or retry only according to the documented OAuth behavior; do not let parallel workers race to overwrite newer credentials.

Run the agent through staged, reviewable steps

Separate discovery, planning, implementation and verification. In discovery, the agent returns the evidence manifest only. In planning, it maps remote fields to an internal model, classifies read and write operations, and identifies retry and idempotency boundaries. Only then should it generate code.

For write endpoints, require an application-owned approval boundary. The agent may propose a payload, but a deterministic service validates the tenant, operation, scope, resource identifier and idempotency key before sending it. High-impact actions such as refund, status change, inventory write or bulk promotion should not be reachable through a general-purpose “call Zid API” tool. Expose narrow tools with explicit schemas and least-privilege credentials.

The execution layer should implement one adapter contract regardless of the agent:

plan -> validate evidence -> build typed request -> authorize tenant
     -> acquire store rate-limit permit -> send -> record sanitized result
     -> verify postcondition or mark outcome unknown

Never give the model raw client secrets or merchant tokens. Tool input should carry a tenant-safe credential reference resolved server-side. Tool output should redact headers and personal commerce data before it returns to an AI context. The same rule applies to traces, screenshots and error bodies.

Make rate limits and retries part of the design

Zid's current rate-limit documentation states a limit of 60 requests per minute per application per store and describes a leaky-bucket approach. Treat that figure as a live contract to verify, not a timeless constant hidden inside code. Put it in provider configuration with a verification date and conservative burst policy.

Allocate one request budget per app and store, not one global counter and not one counter per worker. A fair scheduler should prevent a busy merchant from delaying every other store while still stopping parallel workers for the same store from exceeding its bucket. Reads for user-facing operations may need a different queue priority from reconciliation or analytics, but all priorities must consume the same store budget.

Retry only transient failures and honor server guidance. A `401` should trigger credential diagnosis or a controlled refresh, not an unlimited retry. A `403` means the app or merchant lacks permission. A validation failure needs payload correction. A `429` belongs back in the store's rate-limit queue with jitter and bounded attempts. After an unknown write outcome, read the resource or use an idempotency record before resending.

Measure queue age, requests per store, 429 rate, refresh contention, documentation age, generated-code rejection rate and contract-test failures. These metrics show whether AI assistance is saving engineering time without hiding operational risk.

Verify generated code against fixtures and drift

The agent can write a useful first draft, but tests decide whether the adapter matches the contract. Build sanitized fixtures from documentation examples and controlled sandbox responses. Test missing optional fields, reordered arrays, unknown enum values, expired credentials, wrong-store credentials, malformed pagination and throttling. Keep response parsing tolerant of additive fields while validating required invariants.

Add contract tests for the exact headers without recording their values. Test that the tenant resolver cannot load another store's credential, that secrets never appear in logs, and that an uninstall event blocks new jobs. For writes, test duplicate delivery, timeout after a remote commit and retry after an unknown outcome.

Documentation drift deserves a scheduled check, but not automatic production rewrites. Re-retrieve the pages recorded in the evidence manifest, compare the relevant contract fields and open a review when they change. Regenerate clients or fixtures only after a human confirms the new method, schema or scope. The AI Agent Skill itself notes that it cannot guarantee every answer and does not replace security review or integration testing.

The practical decision

Zid's AI Agent Skill and MCP server are valuable because they reduce the distance between a developer question and the platform's official integration context. Their value is highest when they sit inside a disciplined system: a bounded task contract, live-source evidence, tenant-safe credential resolution, narrow tools, shared rate-limit budgets and executable contract tests.

Do not measure success by how much code the agent generated. Measure how quickly the team can prove that the correct store, endpoint, scopes, headers, failure rules and postconditions are represented. Let the agent accelerate retrieval and drafting; let deterministic controls and tests decide what is allowed to reach production.

Prepared by: Noor Yasser