AWSAWS Certified Generative AI Developer - Professional2026-102.1 Implement agentic AI solutions and tool integrations
Match MCP clients to tool contracts
Completed by the knowledge check
Learning objective
Use MCP client libraries and protocol-defined tool contracts for interoperable agent-tool integration.
Core idea
The Model Context Protocol (MCP) gives an agent a standard way to discover and invoke tools. Interoperability comes from agreement on the protocol revision, transport, tool names, schemas, and result semantics. An HTTP endpoint that accepts arbitrary JSON is not enough.
Use an MCP client library to handle protocol messages and connection lifecycle, then put application controls around the tools it exposes. A library does not decide which tools a tenant may use, whether a result satisfies the business task, or whether a timed-out mutation is safe to repeat. Keep those decisions explicit. See 2.1.10 for server-side validation and 2.1.11 for side-effect recovery.
How it works
Establish a compatible protocol path
Amazon Bedrock AgentCore Gateway exposes tools through an MCP endpoint. Its documentation lists support for protocol versions 2025-03-26, 2025-06-18, 2025-11-25, and 2026-07-28. The configured gateway accepts versions in protocolConfiguration.mcp.supportedVersions. Check that configuration against the client’s supported revisions before choosing the connection path.
For 2025-11-25 and earlier supported revisions, the client performs an initialize handshake. AWS’s Python examples use streamablehttp_client from mcp.client.streamable_http, create a ClientSession from its read and write streams, and call session.initialize(). The connection context encloses discovery and invocation so tools remain available while the agent uses them.
Do not generalize that sequence to every revision. AWS documents 2026-07-28 as a stateless revision without an initialize handshake. Requests carry the protocol version in both MCP-Protocol-Version and _meta.io.modelcontextprotocol/protocolVersion; capability discovery uses server/discover. On that revision, Gateway requests also carry Mcp-Method, and tools/call adds Mcp-Name. Select a client that implements the chosen revision rather than mixing its headers with an incompatible initialization flow.
Transport and authentication are separate compatibility checks. AWS’s Gateway examples send requests to /mcp with Accept: application/json, text/event-stream and an authorization header. A client transport handles the protocol exchange; it still needs credentials accepted by that endpoint. For inbound and outbound access boundaries, see 2.1.4.
Discover the actual tools
Use tools/list to discover tool definitions instead of copying names from a prompt. AWS’s ClientSession example calls session.list_tools() and follows nextCursor until discovery is complete. An application that reads only the first page can falsely conclude that a required tool does not exist.
The tool contract identifies the name, explains behavior in description, and defines arguments in inputSchema. AWS’s ToolDefinition requires those three fields and optionally includes outputSchema. In the MCP 2025-11-25 tool specification, inputSchema is JSON Schema and outputSchema, when supplied, describes structured output.
Treat discovery as input to application policy. Expose only an approved tool set to the model and verify that the discovered schemas match the release you tested. A description helps selection, but it does not grant authority. The MCP specification explicitly treats tool annotations as untrusted unless they come from a trusted server. Claims about being read-only or idempotent are not substitutes for enforcement.
Use the exact discovered name when invoking. AWS’s examples include names such as LambdaTarget___get_order_tool; a gateway-visible name can include a target prefix. Do not reconstruct it from a local Python function name. Keep any mapping between business capabilities and remote names in a reviewed adapter.
The client opens the path its protocol revision defines, follows every nextCursor before discovery is complete, and invokes only an approved tool by its exact discovered name.
Invoke and interpret the result
For an initialization-based revision, an illustrative tools/call body has this shape:
{
"jsonrpc": "2.0",
"id": "REQUEST_ID",
"method": "tools/call",
"params": {
"name": "DISCOVERED_TOOL_NAME",
"arguments": { "order_id": "ORDER_ID" }
}
}Replace REQUEST_ID with the request correlation ID, DISCOVERED_TOOL_NAME with the approved name from discovery, and ORDER_ID with a validated order identifier. The HTTP transport and credentials surround this body. The JSON-RPC id correlates a response; it is not the business idempotency key for an order mutation.
AWS’s Python client example uses session.call_tool(name=..., arguments=...). Its Strands example uses MCPClient from strands.tools.mcp.mcp_client with a transport factory and invokes call_tool_sync inside the client’s context. These are library interfaces over the MCP contract, not alternative server protocols.
Inspect each response layer. HTTP errors can indicate authentication, authorization, or transport failure. A JSON-RPC error object indicates a protocol or service error. A tool result can instead report isError: true for an execution failure. In the 2025-11-25 contract, successful results can contain content blocks and structuredContent; validate structured results against outputSchema when the tool provides one. Preserve the distinction before converting the result into agent context.
An HTTP success alone proves little. AgentCore Runtime’s MCP contract documents several service exceptions returned inside a JSON-RPC body with HTTP 200. Parse the body and classify the actual outcome. Apply a bounded retry policy only after determining whether the operation is safe to repeat.
Key distinctions and trade-offs
Protocol compatibility and business compatibility answer different questions. Two clients can understand the same tool schema while disagreeing about whether an order belongs to the caller or whether a price includes tax. Keep those semantics in the application contract and enforce them in the tool service.
A client library reduces handwritten message handling but adds a versioned dependency to your integration. Test its supported protocol revision, discovery pagination, credentials, and error mapping. A framework adapter such as Strands MCPClient improves agent integration while still requiring the same checks.
A stateless protocol revision does not mean the business operation has no state. An order tool can access durable records on every request. Conversely, a persistent client connection does not establish durable action identity. Choose hosting for lifecycle and resource needs; see 2.1.13.
Architecture / decision scenario
A support agent must use order tools hosted behind AgentCore Gateway and a partner’s remote MCP endpoint. The team chooses 2025-11-25 because both servers and the selected client support it, then uses the library’s initialization-based lifecycle for each endpoint.
Discovery follows every nextCursor. The adapter admits only the approved order lookup and refund tools, verifies their schemas, and preserves their exact remote names. The model proposes arguments; application code checks tenant context and approval before the client dispatches a refund. Its stable business action key survives reconnects and retries independently of JSON-RPC request IDs.
The partner returns HTTP 200 with isError: true when an order is ineligible. The adapter records a business rejection and gives the agent a safe explanation. A JSON-RPC error object, even inside an HTTP 200 response, takes a different path. Neither response becomes a successful refund merely because the HTTP exchange succeeded. A future move to 2026-07-28 requires a compatible client and lifecycle review before changing the gateway’s accepted revisions.
Common exam traps
- Treating arbitrary REST JSON as an MCP tool contract.
- Applying
initializeto every protocol revision. - Ignoring
nextCursoror inventing gateway tool names. - Confusing JSON-RPC request IDs with business idempotency keys.
- Treating HTTP 200, a tool annotation, or discovery as proof of success or authorization.
What to remember
- Match the client, endpoint, transport, and configured protocol revision.
- Discover and allowlist exact tool names and schemas.
- Keep client contexts open for the operations they support.
- Distinguish HTTP failure, JSON-RPC error, and tool execution error.
- Validate results before using them as evidence or reporting completion.
Knowledge check
An AgentCore Gateway lists only 2026-07-28 in protocolConfiguration.mcp.supportedVersions. The team’s MCP client library implements 2025-11-25 and starts every connection with session.initialize(). Which change gives a compatible integration?
MCP-Protocol-Version: 2026-07-28 header to its requestsinitialize with backoff until the gateway accepts it2026-07-28 , with its headers and server/discovertools/call bodies to the gateway as plain REST requests2026-07-28 is a stateless revision with no initialize handshake: every request carries its version in a header and in _meta , and discovery uses server/discover . Adding the new header to an initialization-based client mixes two incompatible lifecycles; the alternative is to configure the gateway to accept a revision the existing client supports.An agent needs a refund tool behind AgentCore Gateway. The first tools/list page does not include it and returns a nextCursor. The local Python function behind the target is named refund_order. What should the client do?
refund_order , the name of the function that implements the toolnextCursor until discovery completes, then call the exact name it listsLambdaTarget___refund_order , built from the target and function namesA refund tools/call times out, and the MCP client reconnects and resends the call under a new JSON-RPC id. The partner server’s tool annotation marks the refund tool as idempotent. What prevents a second refund?
id , reused on the resent requestid correlates a request with its response; it is not durable business identity, and a reconnect changes the connection anyway. Tool annotations are untrusted unless they come from a trusted server, so the action key the refund service enforces is what makes the retry safe.An adapter treats every HTTP 200 from an AgentCore Runtime MCP server as a completed tool call. One response is HTTP 200 whose body is a JSON-RPC error object with code -32003, “Rate limit exceeded”. How should the adapter classify it?
error object with HTTP 200; only authentication, authorization, and protocol-level request errors use other status codes. A tool execution failure is a different layer, reported in a result with isError: true .References
- AWS, Use an AgentCore gateway
- AWS, List available tools in an AgentCore gateway
- AWS, Call a tool in a AgentCore gateway
- AWS, ToolDefinition
- AWS, MCP protocol contract
- Model Context Protocol, Tools — protocol revision 2025-11-25