Video chapters
- AppEngine MCP: connect AI clients to business APIs
- One connection, progressive service discovery
- Prepare the organization, staff token and training order
- Initialize and list the MCP tools
- Find the service and inspect its signature
- Read a record and unpack the result
- Use the business action and verify the saved state
- Release the hold and handle a refused repeat
- Connect an actual MCP SDK client
- Distinguish transport, protocol and tool errors
- Stateless requests, notifications and alternatives
- Use repository tools for your own collections
- Verify the order in Studio
- Connect safely and verify the business outcome
Written guide
Companion source code
Get the course source code on GitHub. The folder includes the supplied examples and setup instructions. Keep credentials in your own environment; use the maintained API reference when adapting recorded request examples.
Written companion · 10 October 2026 · Recorded protocol, SDK and Studio evidence.
1. AppEngine MCP: connect AI clients to business APIs
MCP exposes AppEngine's registered business services to a compatible client. This course demonstrates a real protocol connection and SDK client, not a staged AI conversation. The order read, hold, release and refusal were executed against a controlled training deployment; the same final order was inspected in Studio.
Watch the course · Download examples
No payment, shipment, external notification or autonomous AI-host run is claimed. The zero-value order is an API fixture, not a completed storefront sale.
Explanation
AppEngine MCP connects an AI client to the business services your application already uses. We will discover those services, read an order, place a controlled hold, and verify the saved result. Then we will release it, connect an actual MCP client, and handle the errors that matter. The goal is a working connection to AppEngine, with a clear understanding of what each tool can do.
2. One connection, progressive service discovery
An MCP tool is the client's entry point; an AppEngine service owns a business area; a service method performs one operation. JSON-RPC wraps calls with a method, parameters and request ID. The sf_order datatype stores order records; each record's sk identifies it and data holds business fields.
list_services returns the current registry. describe_service supplies names, positional parameter order and return descriptions. call_service runs a registered method. Registry counts change; use discovery instead of relying on the number filmed. Use the business action when it supplies needed behavior: orderHold remembers the earlier status and reason, while directly patching status does not implement that operation.
Explanation
The client connects to your AppEngine address at slash MCP. AppEngine exposes three tools. List services finds the business area. Describe service reveals its methods and argument order. Call service invokes the selected method. This keeps the connection small while making many services discoverable. An order hold uses the order service and its business rules; a repository query reads the underlying record. Discovery reveals signatures, not your organization’s records. Data calls require the configured organization and an authenticated principal.
3. Prepare the organization, staff token and training order
Open Appmint Studio. The Introduction course explains signup, organization and finding your endpoint. For staff sign-in, open the Database & Repository video and choose 1:02 · Use the staff identity and organization. The written setup instructions provide the same prerequisite in text. Keep the exact API endpoint, orgid and returned staff token. A challenge response must be completed before it is a usable session.
The downloaded 01-staff-signin folder contains a complete JSON body with placeholders. Send it to POST /profile/user/signin with Content-Type application/json and orgid. Store the returned token privately as STAFF_TOKEN; later data calls send Authorization: Bearer plus that token. Current MCP invocation checks content read permission before directly invoking a service. Do not assume every REST controller permission guard is repeated. A successful connection alone is not permission to run every method.
Use an isolated organization and an order you own. To reproduce the film without purchasing anything, edit the complete 07-create-isolated-order/request.json: choose a unique order number and your training email. Read first to ensure that number is unused, then create the zero-value fixture once. Save its returned sk. Replace MCP1010A in subsequent calls with your number; getOrderById instead uses sk. The example package explains cleanup and includes the entire payload.
Explanation
Use your organization’s AppEngine endpoint and organization ID. For this course, sign in as staff with profile user signin and the orgid header. The Database and Repository video demonstrates this in chapter two, linked in the companion. Keep its returned token private and configure it as a bearer credential. The MCP gateway requires content read permission before invoking a service; do not assume it repeats every REST controller permission check. Our order is an isolated, zero-value API fixture, not evidence of checkout or payment. The download includes its complete creation payload.
First request in this chapter
POST /profile/user/signin
{
"email": "YOUR_STAFF_EMAIL",
"password": "YOUR_STAFF_PASSWORD"
}4. Initialize and list the MCP tools
POST the initialize JSON to /mcp. Inspect the echoed ID, protocolVersion, serverInfo and tools capability. Then POST tools/list to discover the three tool schemas. This deployment accepted protocol version 2025-06-18; the server also contains negotiation for its other supported versions. Use the returned version and your client SDK's negotiation behavior.
The client may send notifications/initialized after initialization; it has no request ID and receives an empty 202 response here. Do not JSON-parse empty content. This server is stateless: data calls still carry orgid and bearer headers on every request. Discovery can work without them, while sending an invalid credential can fail authentication before discovery runs.
Explanation
Send a JSON RPC initialize request to the MCP endpoint. Its ID connects the response to this request. This deployment accepts the requested protocol version and advertises tools. Next send tools list. The three returned tool schemas tell the client what it can call. Initialization and discovery work without a token. A connected client normally performs these steps for you; doing them once here makes the connection understandable. Each data call still sends its own organization and authorization headers.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "appengine-course",
"version": "1.0"
}
}
}5. Find the service and inspect its signature
Use tools/call with name list_services, then describe_service with arguments.service exactly StorefrontOrderService. Inspect orderHold's signature before invoking it. The current registry injects a leading orgId or orgid from the HTTP context. Omit only that injected parameter: the remaining args array contains orderNumber followed by holdInfo.
The method's reason is inside an object, not a second string. User-related parameters are not automatically populated merely because of their names. Read each signature. The full describe response is downloaded; the video selects the order methods so the fields remain readable.
Explanation
Call list services through tools call. Here is Storefront Order Service and its available method names. Next call describe service with that exact service name. Find order Hold. Its signature includes orgId, orderNumber and holdInfo. The server injects a leading organization parameter from request context. Your args array contains the remaining values in declaration order: the public order number, then the reason object. Do not insert the organization again. Other parameters, including user-related parameters, are not automatically supplied just because they sound like an identity. Read the actual signature.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "list_services",
"arguments": {}
}
}6. Read a record and unpack the result
Call RepositoryCrudService.findByAttribute with sf_order, plain attribute number, your order number, and paging options. AppEngine looks inside data for that attribute. Confirm total and the matching data.number before changing anything.
Read three layers: the transport response, any top-level JSON-RPC error, and result.isError. Successful tool output carries content blocks; locate the text block and parse its text as JSON. HTTP200 can still contain result.isError true. Do not parse an error string as if it were a success object. The downloaded runners print the full response and return a failure exit code for protocol/tool errors.
Explanation
Before a change, read the order. Repository Crud Service find By Attribute takes the datatype, attribute, value and options after the injected organization. Here the attribute is number, and total is one. MCP wraps the service result as text inside content. Check the matching request ID, then isError, then parse that text as JSON. The order number matches and its status is processing. HTTP two hundred alone does not establish success: a tool failure can use the same HTTP status.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "call_service",
"arguments": {
"service": "RepositoryCrudService",
"method": "findByAttribute",
"args": [
"sf_order",
"number",
"MCP1010A",
{
"page": 1,
"pageSize": 5
}
]
}
}
}7. Use the business action and verify the saved state
Send StorefrontOrderService.orderHold with ["YOUR_ORDER_NUMBER", {"reason":"Controlled training hold"}]. The observed response contains status on_hold, previousStatus processing, holdReason and heldAt. Run the read request again and verify those values persisted.
Read before retrying any mutation after an uncertain response. This implementation permits another hold on an already-held order and overwrites previousStatus with on_hold. Repeating blindly can lose the state release was meant to restore. Current history.from also repeats the destination in this execution; use the directly observed before/after record state rather than presenting that history field as reliable proof. Terminal cancelled/refunded/delivered/completed orders are rejected by the current service; the filmed error demonstration is repeat release, not every terminal case.
Explanation
Call order Hold with the order number and a reason. The returned order is on hold, previousStatus retains processing, and holdReason stores our reason. Now run the read again: the saved record is on hold too. Use this business action instead of writing only a status field. Before retrying a mutation after an uncertain response, read the current record. Do not blindly repeat hold on an already held order: that can overwrite the previous status you need for release.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "call_service",
"arguments": {
"service": "StorefrontOrderService",
"method": "orderHold",
"args": [
"MCP1010A",
{
"reason": "Controlled MCP course hold"
}
]
}
}
}8. Release the hold and handle a refused repeat
Call orderRelease with only the public order number. A separate findByAttribute read verifies processing again. previousStatus and holdReason disappear; heldAt can remain. Repeating release returns HTTP200 with result.isError true and the text “Order is not on hold”. The refusal leaves the saved state unchanged.
Keep the order fixture if you want to revisit the chapters. For cleanup, delete only the returned fixture sk through the Repository API and verify its absence. This is cleanup of a training record, not the business cancellation action for a real order.
Explanation
Release takes only the public order number. The returned status is processing again, and a separate read confirms it. The hold reason and previous status have been cleared. Repeating release now returns isError true with Order is not on hold. That is the business rule refusing an invalid transition. Use the saved state and returned reason to decide what to do next; do not keep repeating the same action.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"id": 9,
"method": "tools/call",
"params": {
"name": "call_service",
"arguments": {
"service": "StorefrontOrderService",
"method": "orderRelease",
"args": [
"MCP1010A"
]
}
}
}9. Connect an actual MCP SDK client
The downloadable mcp-client.mjs uses the actual MCP SDK Client and StreamableHTTPClientTransport. In a new example folder run npm init -y, then npm install @modelcontextprotocol/sdk. Set APPENGINE_ENDPOINT, ORG_ID, STAFF_TOKEN and ORDER_NUMBER privately. Run node mcp-client.mjs.
The program connects, lists tools, calls RepositoryCrudService.findByAttribute and prints the parsed record. The recorded SDK output confirms all three tools, total 1 and Processing. It intentionally performs a read, so running the client does not mutate the order.
An AI host adds model-selected calls on top of this protocol. Configure an HTTP MCP server URL ending in /mcp, an orgid header and private bearer header in a client that supports them. Never put the token in a user prompt. Suggested instruction: “Read this order. If it is on hold, release it once. Read again and report the saved status.” Inspect the actual tool log and final readback. This prompt is a configuration example, not an executed AI run. Connect an AI client covers host-specific setup; this course's verified client is the SDK program.
Explanation
Now connect a real client. This example uses the installed MCP SDK with its streamable HTTP transport. Configure the URL ending in slash MCP, the orgid header and the bearer token from your environment. Connect, list tools, then call the repository method. This actual client found all three tools and read our order in processing state. The complete runnable example is in the download. An AI host uses the same connection, but chooses calls from a prompt. Configure its headers privately and inspect its tool log. The sample prompt is a suggested instruction, not a claimed autonomous AI run.
10. Distinguish transport, protocol and tool errors
The filmed missing-token request returns a tool-level authentication error. In this deployment, omitting orgid also prevents principal resolution and produces authentication-required, rather than the draft's promised missing-org wording. Follow the response you actually receive.
Unknown service and unregistered method produce tool errors; an unknown JSON-RPC method produces a top-level error. Correct names using fresh discovery. If a token expires, renew it through the supported authentication procedure before retrying; an expired bearer may cause HTTP401 before MCP dispatch. Failure recovery is different from retrying a write: inspect current saved state if the earlier result is uncertain.
Explanation
A missing bearer token makes call service return a tool error, while discovery still works. In this deployment, omitting orgid also prevented the principal from resolving, so the observed message was authentication required. An unknown service or method produces a tool error with the exact name to correct. An unknown JSON RPC method instead returns a top-level error. Keep these layers separate. Start by fixing the connection or signature, and read the record before retrying any action whose outcome is uncertain.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"id": 12,
"method": "tools/call",
"params": {
"name": "call_service",
"arguments": {
"service": "RepositoryCrudService",
"method": "findByAttribute",
"args": [
"sf_order",
"number",
"MCP1010A"
]
}
}
}11. Stateless requests, notifications and alternatives
The endpoint accepts POST JSON-RPC. GET returns 405 because this implementation has no server event stream. resources/list and prompts/list returned empty arrays in this run. Notifications omit id and receive no JSON-RPC reply.
A batch array may contain independent requests plus notifications. Each response retains its request ID, while notifications have no response entry. The implementation executes batch messages concurrently. Do not put a mutation and its dependent verification read into the same batch expecting ordering. Send the read after the mutation completes.
The video displays a summary of batch response IDs; complete request and response envelopes are in folder 23-batch.
Explanation
This endpoint is stateless. An initialized notification has no request ID and receives HTTP two oh two with an empty body. Do not force an empty successful response through a JSON parser. GET returns four oh five because this server does not offer an event stream. Resources and prompts return empty lists here. A batch can contain several independent messages; responses keep their IDs, and notifications produce no reply entry. The server runs batch messages concurrently, so send a dependent read only after its write has returned.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}12. Use repository tools for your own collections
The Repository tools also access custom collections. The film reads workflow_lab_1010 with a query on data.status equal to approved. This record comes from the Workflow course. Alternatively, Database & Repository APIs teaches creating your own collection and records. Replace the datatype and field query with your actual saved collection; an empty array is not a connection failure.
findByAttribute takes a plain business-field name such as number. find takes an explicit query such as {"data.status":"approved"}. Paging options follow the query. Repository operations remain subject to platform behavior and do not replace specialized business actions.
Explanation
For data without a built-in business type, use a custom collection created through the Database and Repository course. The same MCP call service tool can invoke Repository Crud Service find. This query uses the full field path data dot status, unlike the plain attribute name used by find By Attribute. The result contains the matching approved training record. Discover the service, inspect the signature, and preserve the organization context; you do not need a separate MCP endpoint for each collection.
First request in this chapter
POST /mcp
{
"jsonrpc": "2.0",
"id": 19,
"method": "tools/call",
"params": {
"name": "call_service",
"arguments": {
"service": "RepositoryCrudService",
"method": "find",
"args": [
"workflow_lab_1010",
{
"data.status": "approved"
},
{
"page": 1,
"pageSize": 5
}
]
}
}
}13. Verify the order in Studio
In Studio open Storefront → Order. In Order Center, use Search orders and type the exact public order number. The filmed result is MCP1010A, with a zero total and Processing badge. That matches the release readback; it is the same organization and saved order, not a second mock UI.
The live browser was captured at 1920×1080 CSS pixels with DPR2 (4K source) and downsampled for the 1440p course. Highlight rectangles were measured against the actual order and status controls. The video does not display a localhost address as a production endpoint.
Explanation
In Order Center, search for M C P ten ten A. Here is the same training order. Its Processing status matches our release result from the API.
14. Connect safely and verify the business outcome
Use discovery to find the next business area, then inspect its exact signature and verify its result. Related courses: Workflow and Approvals, Database and Repository, Authentication, and AI Employee APIs.
The course demonstrates MCP transport and concrete business-service calls. AI-host tool selection, an entire storefront checkout and every exposed service remain distinct subjects; they are not claimed by the order fixture.
Explanation
You now have the complete MCP path: configure the connection, discover the service, inspect its signature, call the method and verify the saved result. The companion includes the training fixture, raw JSON requests, client code and the important alternatives. Keep credentials in client settings, review tool errors as well as HTTP status, and read back an uncertain mutation before deciding to retry. That is how your AI client stays connected to the actual AppEngine business state.
Limitations and checks
25 recorded request/response exchanges, one real SDK connection/read, and Studio readback. Source: AppEngine MCP controller/service and AI-callable registry; StorefrontOrderService hold/release; RepositoryCrudService. No application source changes were made. The API fixture is not checkout/payment proof. AI-host prompt execution is unrecorded. Histories have the specific limitation described in the hold chapter.
Producer checked scene layout, spoken-cue alignment and source audio. Initial narration and selected source/evidence were independently reviewed before the other production agents hit a usage limit. Final assembly remains producer-reviewed; no independent continuous audiovisual acceptance is claimed.