---
title: "Design an integration"
description: "Use the design_integration MCP tool to turn app-builder and architecture choices into an agent-ready Inttegro build and test plan."
canonical: "https://studio.inttegro.com/inttegro-mcp/design-integration"
format: inttegro-machine-docs/v1
language: "cURL"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/curl/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 552
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "curated"
recommended_mcp_tools: ["design_integration","check_integration_readiness","get_integration_guide"]
estimated_tokens: 2871
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Use the read-only design_integration tool to turn five declared architecture choices into a versioned build and test brief; unresolved conflicts and readiness checks remain explicit.

### Five questions

#### Q1. Which inputs does the tool need?

Declare the commerce goal, trusted server runtime, SDK preference, checkout approach, and optional app builder. If a client supports elicitation it can collect missing decisions; otherwise ask the merchant and pass the strict arguments. See [choose the architecture](https://studio.inttegro.com/machine/curl/inttegro-mcp/design-integration.md#choose-the-architecture).

#### Q2. Can the tool accept credentials or infer an architecture silently?

No. Do not send secrets or invented partial objects. Conflicting choices, such as hosted-checkout goal with custom checkout, produce a warning that must be resolved with the merchant before implementation.

#### Q3. What should a coding agent carry forward?

Use the returned required operations, implementation steps, test plan, canonical docs, and self-contained agent brief. Follow linked API and SDK pages for exact symbols rather than inventing request fields from the plan. See [understand the plan](https://studio.inttegro.com/machine/curl/inttegro-mcp/design-integration.md#understand-the-plan).

#### Q4. Does a readiness check prove deployed behavior?

[check_integration_readiness](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#check_integration_readiness) audits declared controls such as secret storage, idempotency, authoritative lookup, checkout returns, and consent. It does not inspect private code or prove a live payment; run disposable end-to-end tests and read current resource state.

#### Q5. When should this tool be used rather than a generic guide?

Use [design_integration](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#design_integration) at the start when builder, server, SDK, and checkout choices need a coordinated plan. For a focused known workflow, [get_integration_guide](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#get_integration_guide) can return a shorter sequence and canonical links.

## Document content

# Design an integration

`design_integration` is a read-only MCP tool that turns five practical 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, app builder, 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 five inputs:

| Input             | Choices                                                                                                                     | What it controls                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `goal`            | `hosted_checkout`, `custom_checkout`, `orders_and_invoices`, `catalog_and_buy_links`, `customer_messaging`, `full_commerce` | The smallest complete merchant workflow and its initial API operations                           |
| `server_language` | `typescript`, `go`, `python`, `php`, `ruby`, `java`, `dotnet`, `other`                                                      | The trusted server runtime and available SDK installation guidance                               |
| `use_sdk`         | `true` or `false`                                                                                                           | Whether the plan recommends an official SDK or direct HTTPS                                      |
| `checkout`        | `inttegro`, `custom`, `none`                                                                                                | Whether customers use Inttegro Checkout, a custom checkout, or no checkout in the first workflow |
| `app_builder`     | `base44`, `bolt`, `google_ai_studio`, `lovable`, `replit`, `v0`, `other`                                                    | The platform-specific planning path, trusted runtime, and secret-storage boundary                |

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 five choices:

```json
{
  "goal": "catalog_and_buy_links",
  "server_language": "typescript",
  "use_sdk": true,
  "checkout": "none",
  "app_builder": "replit"
}
```

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:

| Field                  | Meaning                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| `plan_version`         | The version of the planning rules used to create the result                              |
| `selections`           | The five resolved architecture decisions                                                 |
| `recommended_path`     | A compact SDK-or-HTTPS and checkout recommendation                                       |
| `rationale`            | Reasons for the recommended server and checkout approach                                 |
| `install_command`      | The official SDK installation instruction, or `null` for direct HTTPS                    |
| `required_operations`  | The smallest initial set of Inttegro API operations for the selected workflow            |
| `builder_guidance`     | Platform-specific connection, runtime-boundary, and credential-storage instructions      |
| `implementation_steps` | Ordered server boundary, client, workflow, checkout, and production-control instructions |
| `test_plan`            | Authentication, idempotency, workflow, failure, and state-verification tests             |
| `documentation`        | Canonical Studio pages supporting the selected architecture                              |
| `warnings`             | Inconsistent choices or unavailable SDK guidance that must be resolved                   |
| `agent_brief`          | A 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.

## Related guides

- [Build with AI](https://studio.inttegro.com/machine/curl/ai-builders.md) provides ready-to-use paths for Base44, Bolt,
  Google AI Studio, Lovable, Replit, and v0.
- [Build an integration with an agent](https://studio.inttegro.com/machine/curl/inttegro-mcp/build-integrations.md) describes the complete design, focused-guide, and readiness workflow.
- [Tool catalog](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md) lists every MCP tool.
- [Authentication](https://studio.inttegro.com/machine/curl/api/authentication.md) explains trusted-server API authentication.
- [SDKs](https://studio.inttegro.com/machine/curl/sdks.md) lists supported SDKs and installation instructions.
- [Idempotency](https://studio.inttegro.com/machine/curl/api/idempotency.md) explains safe mutation retries.