Skip to main content

Design an integration

design_integration is a read-only Inttegro MCP tool that turns four architecture decisions into a versioned implementation plan. Use it at the beginning of an integration when a merchant and their agent need to agree on the first workflow, server runtime, SDK choice, and checkout experience.

The result is written for both people and coding agents. It includes the initial API operations, ordered implementation steps, an end-to-end test plan, canonical Studio links, and a self-contained agent_brief that can be handed to another agent.

Start the conversation

Ask an Inttegro-connected agent:

Help me design our Inttegro integration. Ask me the architecture questions one at a time, then give my coding agent exact build and test instructions.

The agent calls design_integration. If its MCP client supports input elicitation, the client presents a form for the missing decisions. In other clients, the agent can ask the questions conversationally and pass the answers as tool arguments.

The tool does not accept credentials. Do not paste an API key, customer data, source code, or production secrets into the conversation.

Choose the architecture

The tool resolves these four inputs:

InputChoicesWhat it controls
goalhosted_checkout, custom_checkout, orders_and_invoices, catalog_and_buy_links, customer_messaging, full_commerceThe smallest complete merchant workflow and its initial API operations
server_languagetypescript, go, python, php, ruby, java, dotnet, otherThe trusted server runtime and available SDK installation guidance
use_sdktrue or falseWhether the plan recommends an official SDK or direct HTTPS
checkoutinttegro, custom, noneWhether customers use Inttegro Checkout, a custom checkout, or no checkout in the first workflow

Choose the trusted backend language, not the browser framework or mobile language. Inttegro API keys belong in trusted server infrastructure even when the customer experience runs in a browser or native app.

If the checkout choice conflicts with the stated goal, the plan returns a warning rather than silently changing the decision. For example, hosted_checkout combined with custom checkout must be resolved before implementation.

Supply the choices directly

Harnesses without an interactive form can call the tool with all four choices:

{
  "goal": "catalog_and_buy_links",
  "server_language": "typescript",
  "use_sdk": true,
  "checkout": "none"
}

Arguments are strict. Unknown fields, credentials, and partial architecture objects are not treated as a completed design. When choices are missing, a compatible client receives an input request for the complete decision set.

Understand the plan

design_integration returns structured data so any compatible agent can use the same result:

FieldMeaning
plan_versionThe version of the planning rules used to create the result
selectionsThe four resolved architecture decisions
recommended_pathA compact SDK-or-HTTPS and checkout recommendation
rationaleReasons for the recommended server and checkout approach
install_commandThe official SDK installation instruction, or null for direct HTTPS
required_operationsThe smallest initial set of Inttegro API operations for the selected workflow
implementation_stepsOrdered server boundary, client, workflow, checkout, and production-control instructions
test_planAuthentication, idempotency, workflow, failure, and state-verification tests
documentationCanonical Studio pages supporting the selected architecture
warningsInconsistent choices or unavailable SDK guidance that must be resolved
agent_briefA self-contained implementation assignment for a coding agent

For the catalog and buy-link example above, the plan begins with country capability discovery, product creation, price creation, purchase-intent creation, and purchase-intent lookup. It also tells the coding agent to use integer minor units, stable idempotency keys, bounded timeouts, sanitized logs, and read-after-ambiguous-write verification.

Hand the brief to a coding agent

Keep the structured result intact and ask the agent to treat the linked Studio pages as the API contract:

Implement the returned agent_brief. Follow its required_operations in order, use the linked Studio documentation for exact request and response fields, and complete every item in test_plan. Stop and report any contract mismatch instead of inventing a field.

An agent with repository access can then inspect the application, implement the server-side integration, and run the tests. design_integration itself does not inspect a repository, edit code, create an API key, deploy an application, or prove that production traffic works.

Verify readiness

After implementation, use check_integration_readiness to audit the declared controls:

Check whether this integration is ready for an end-to-end test. Verify server-side secret handling, idempotency, response errors, authoritative order-state lookup, checkout return paths, and messaging consent where applicable.

The readiness result reports each control as pass, fail, or not_applicable, lists blockers, and returns the end-to-end test sequence. It evaluates the facts supplied by the merchant or coding agent; it does not receive secrets or independently inspect private code.

Run the final test with disposable fixtures. A successful redirect or mutation response is not enough when the workflow has an authoritative lookup operation—verify the resource state before production rollout.