Design an MCP adapter for an app without one

Start from an approved business API

Choose one business task before designing the adapter. A read of approved ticket counts or inventory availability is easier to evaluate than a generic tool that exposes an entire application. Identify the user, the records they may access, and the result needed for the decision. That scope should drive the tool contract and the source requests.

Preserve source meaning

Map source fields deliberately and document the business interpretation. A status code, date, or amount may carry conventions that are obvious to the source application but unclear to an assistant. Return enough structured context for the consumer to understand the result, including relevant scope and limitations. Avoid flattening meaningful distinctions merely to produce a shorter response.

Handle pagination and partial coverage explicitly. A tool that returns the first page should not imply that it has counted the whole population. Rate limits and source failures also need visible behavior. The adapter should report what it could establish, rather than turning incomplete retrieval into a confident business summary.

Design identity first

Determine whether calls should use each user's source authorization or an approved service identity with a defined scope. Document how the adapter associates an assistant request with the allowed source context. Never accept a user-supplied tenant or account identifier as sufficient authority to access that population. The source boundary must remain effective throughout the request.

Keep credentials out of tool arguments, model-visible results, logs, and demonstration recordings. Use the organization's supported secret-management and authorization practices. Revocation and permission changes should be testable. A custom adapter that works only with a permanently privileged token creates an operating risk that a polished conversational interface cannot conceal.

Make the contract narrow

Define explicit inputs with bounded filters and limits. Validate them before calling the source. Return a predictable result and typed failure information that the consumer can handle. If the initial purpose is read-only, do not add write operations merely because the vendor API supports them. Each state-changing capability deserves a separate review.

Test ordinary results, empty results, denied access, missing records, source outages, and malformed requests. Use vendor-approved test environments where available. Include two users with different permissions and verify the complete response for leakage. Connectivity is a prerequisite; it is not the acceptance criterion for the adapter.

Evaluate before promising support

Document the tested application edition, API version, credential mode, supported operations, and known limitations. A prototype for one environment is not universal support for every installation of that vendor's product. Keep maturity labels clear as the adapter moves from experiment to a supported integration.

Bring an unsupported application request to dotSolved with the business questions and the vendor's official API documentation. Nexatron's existing connector catalog should be checked first; a custom adapter is a scoped engineering engagement where needed. Keep the requested adapter in candidate status until the source contract, authorization model, and bounded acceptance cases have been reviewed and an implementation owner has accepted the scope.

A first adapter acceptance case

Choose one small read operation and define an exact expected result for two authorized identities with different scopes. Add an empty result and a denied request. If the adapter can represent these states clearly and preserve pagination limits, it has a useful foundation for further evaluation. Passing this narrow case does not certify the full vendor API; it establishes evidence for the specific contract you built.

Preserve the denied case when adding another operation; broader functionality must not erase the original boundary.