Chapter 7: Tool integration and MCP

Introduction

This introduction explains why connecting AI assistants to external systems becomes fragile at scale and presents MCP as a standardized alternative to one-off integrations.

• Custom integration scaling problem: Explain why an assistant answering a product question may need external systems and why connecting each new API and app with custom code scales poorly.
  Why it matters: The scaling problem explains why a shared way to connect assistants and tools is useful.
• MCP standardized connectivity: Describe MCP as the proposed standard for connecting AI systems to external services without writing a separate custom integration for every API.
  Why it matters: A common connection standard addresses the duplicated integration work described in the introduction.

Key terms: glue code, one-off integrations, Model Context Protocol (MCP), standard, plug-and-play connectivity

7.1 What is MCP?

The section illustrates how custom integrations can make an AI assistant fragile and why integration complexity grows as organizations use many data sources.

• Custom integration complexity: Explain why connecting an AI assistant to external services can become difficult to maintain, using the inventory, Slack, and payment example and the scale of enterprise data sources.
  Why it matters: This is the integration problem the chapter sets out to address.

Key terms: custom Stripe integration, Slack webhooks, N×M integration nightmare, integration complexity

7.2 The hidden complexity: The N×M problem

This section shows why connecting each AI application separately to every external API creates a growing integration and maintenance burden.

• The N×M integration problem: Explain how separate connections between every AI application and every external API create an N×M set of custom integrations, and why changes can require widespread refactoring.
  Why it matters: Recognizing the repeated integration work makes the need for a shared approach clear.

Key terms: N×M problem, custom glue code, custom integrations

7.3 The solution: MCP

This section explains how MCP standardizes connections between AI apps and tools while leaving tool execution and endpoint security to developers.

• Standardized app and tool connections: Explain how MCP reduces the number of custom integrations by giving each external tool a standard server and each AI app reusable client logic.
  Why it matters: This is why adding another app or tool need not require a new integration for every pairing.
• Standard interface versus tool execution: Distinguish MCP’s standardized tool interface from the execution logic developers must still implement behind a tool.
  Why it matters: A standard connection does not make the underlying tool work automatically.
• Protocol and security boundaries: Explain which concerns MCP handles and which security responsibilities remain with developers.
  Why it matters: Plug-and-play integration must not be mistaken for a secure deployment.

Key terms: MCP server, MCP client, plug-and-play integration, execution logic, boilerplate, interface, schema validation, error formatting, authentication, authorization

7.4 Building your first real MCP tool with a CSV-powered product catalog

Introduces a CSV-backed product catalog as a practical starting point for building and testing an MCP tool.

• CSV Catalog Data Source: Justify using a flat CSV file rather than a live e-commerce API for the first product search tool.
  Why it matters: The simpler data source lets you focus on the tool without first solving API access and setup problems.

Key terms: CSV file, product search tool, product catalog

7.4.1 Loading your product catalog

This subsection sets up a CSV product catalog as a simple source of truth for testing product search.

• CSV product catalog structure: Describe how products.csv serves as the product-search database and what each product field means.
  Why it matters: The catalog gives the search tool structured product data to use without requiring a backend yet.

Key terms: products.csv, source of truth, in-memory database, id, title, price

7.4.2 Setting up the MCP server

This section explains how to expose a CSV-backed product search as an MCP tool and return results in a format an LLM can use.

• MCP server setup: Explain how FastMCP and pandas support the product tool, and why the CSV is loaded once at startup.
  Why it matters: This separates the tool’s product-search logic from MCP plumbing and repeated file loading.
• Product search filtering: Trace how search_products narrows the catalog using its arguments and excludes unsuitable results.
  Why it matters: These steps determine which products a search can safely return.
• Structured product results: Describe the form of the tool’s final output and why it is useful to an LLM.
  Why it matters: A straightforward result format makes the tool’s findings easier for the model to use in its answer.

Key terms: FastMCP, pandas, MCP-compatible tools, search_products, DataFrame, search query, price limit, list of dictionaries, JSON-like data

7.5 Running and testing your server

This section shows how to start the MCP server and test its product-search tool from a command-line prompt.

• Running the MCP server: Describe what happens when you run the server script and how you can tell it is ready for tool calls.
  Why it matters: You need the server running before a client can call its tools.
• Testing product search calls: Explain how mcp-dev lets you test the tool and what the example searches reveal about its results.
  Why it matters: Testing calls directly lets you check the tool’s search behavior before involving an AI model.

Key terms: FastMCP, Server-Sent Events (SSE) server, MCP clients, tool calls, mcp-dev, MCP tools, empty list, in stock

7.5.1 Why this matters

This section explains why a data-backed MCP product-search tool is a foundation for an AI shopping assistant.

• Data-backed product search: Explain how the assistant can turn a vague shopping request into a specific product search and use the resulting product data in its response.
  Why it matters: The tool connects a shopper’s imprecise request to product data the assistant can use rather than relying on a vague answer.

Key terms: MCP tool, search_products, product data, max price

7.5.2 Next steps

The section establishes that the completed MCP server serves real product data to MCP-compatible AI models, then previews model-driven tool use.

• Completed MCP Server Capabilities: Describe what the completed MCP server provides and which AI models can call it.
  Why it matters: These are the capabilities the next step can build on.

Key terms: MCP server, MCP standard, product data

7.6 Teaching your AI to use MCP tools

This section explains why an MCP tool needs a clear, standardized interface before an LLM can use it effectively.

• Usable tools for LLMs: Explain that LLMs can reason about tools, but this is useful only when the tools are well described, accessible, and standardized—the conditions MCP provides.
  Why it matters: A working tool alone is not enough; the LLM needs a usable way to understand and access it.

Key terms: LLMs, tools, MCP

7.6.1 How models learn what tools they can use

This section explains how an MCP server makes its tools discoverable to a model without manually supplying each tool’s schema.

• MCP tool discovery flow: Trace how a model gains access to tools exposed by an MCP server, and distinguish this from defining functions inline in a request.
  Why it matters: You can expose tools through the server rather than redefining them in every model request.

Key terms: MCP server, /tools/list, tools array, schemas, declarative tool provider

7.6.2 A complete example: Model > MCP > answer

The section traces a product-search request from plain language through MCP tool discovery and execution to a grounded answer, while warning about unapproved tool calls.

• MCP product search flow: Trace how a plain-English product request becomes a search_products tool call and an answer based on the returned products.
  Why it matters: It shows how a defined MCP tool connects a user request to an answer grounded in search results.
• Tool call approval risk: Explain why the example's require_approval setting is unsafe for sensitive production tool calls and what approval the section recommends instead.
  Why it matters: A convenient demo setting can let a production agent take consequential actions without a person approving them.

Key terms: MCP server, /tools/list, schema, search_products, tool call, OpenAI runtime, require_approval, never, always, custom approval logic

7.6.3 What you didn’t have to write

This subsection contrasts manual tool integration with hosted MCP’s declarative tool exposure and automatic discovery.

• Manual integration versus hosted MCP: Explain what developers traditionally had to wire up for model tool use and how hosted MCP changes that work. State that the model discovers tools exposed by the server and calls them when given permission.
  Why it matters: It explains why hosted MCP can simplify connecting a model to tools without removing the need to grant permission.

Key terms: hosted MCP support, glue code, discover, permission, expose capabilities declaratively

7.6.4 Tool design becomes interface design

This section explains why an MCP tool schema is an interface for a language model, not just a definition of a backend service.

• MCP Tool Schema Design: Explain how tool names, descriptions, and arguments affect a model’s ability to choose and use MCP tools. Contrast a vague argument such as “x” with a self-documenting tool definition.
  Why it matters: Clear tool schemas help an agent understand which tool to use and how to use it.

Key terms: MCP server, language-model API surface, tool schema, self-documenting

7.7 Adding a second tool: Inventory status

The section distinguishes product search from inventory lookup and shows how the two MCP tools can serve a customer’s question together.

• Product Search and Inventory Lookup: Explain what each of the server’s two tools does and why a question about a specific item may call for an inventory check after a product search.
  Why it matters: Finding a product and checking its inventory answer different parts of a customer’s question.

Key terms: search_products, check_inventory, MCP server

7.7.1 How models chain tools

Shows how a model answers a two-part product question by calling search and inventory tools in sequence, without hand-written orchestration.

• Automatic tool chaining: Trace how the model searches for waterproof jackets, uses a product ID to check the cheapest jacket’s inventory, and answers with the price and stock status. Explain that the model chooses the tools and their order from the user’s question and tool descriptions, without hand-written orchestration code.
  Why it matters: A question that needs more than one lookup can be answered through a sequence of tool calls rather than a separately coded workflow for that question.

Key terms: tool chaining, search_products, check_inventory, tool descriptions, orchestration code

7.7.2 Tool descriptions guide model behavior

Clear, specific tool descriptions help a model choose the right tool for a task.

• Tool descriptions as routing instructions: Explain how distinct tool descriptions help a model choose between searching for products and checking a specific product’s inventory.
  Why it matters: Distinct descriptions help the model route a request to the tool suited to it.

Key terms: tool descriptions, search_products, check_inventory, discovery, verification, routing instructions

7.8 Handling failures gracefully

This section explains why MCP tools need clear, structured failure responses so an AI model can respond helpfully when tools fail.

• Structured tool failure responses: Explain why MCP tools should return structured information about failures rather than a Python stack trace, and describe how that helps the model respond to users.
  Why it matters: A useful failure response gives the model a way to help the user even when the tool cannot complete the request.

Key terms: MCP tools, structured information, clear error responses, Python stack trace

7.8.1 Catching and communicating errors

7.8.2 Why structured responses matter

The section explains how consistent, structured tool responses help a model recognize outcomes, communicate with users, and choose a next step.

• Structured Tool Response Benefits: Explain how a consistent response structure helps a model determine whether an operation worked, communicate its result, and decide what to do after an error.
  Why it matters: A predictable response gives the model usable information instead of leaving it to guess what happened.

Key terms: structured responses, success, message, error codes

7.8.3 Handling empty results vs. errors

The section distinguishes an unsuccessful search from a failed tool call and explains how the model should respond to each.

• Empty Results Versus Errors: Distinguish a successful search with no matches from a tool error, and explain how the model can respond differently to each.
  Why it matters: Keeping these outcomes separate lets the assistant remain helpful when nothing matches without pretending a broken tool worked.

Key terms: empty results, error, success: True, success: False

7.8.4 Timeout and rate-limiting

This section explains how MCP tools can remain useful when external APIs are slow or fail by using timeouts, retries, and clear error responses.

• Timeouts and backoff retries: Explain why an external API call needs a timeout and how retries with exponential backoff can keep a transient network error from failing the entire request.
  Why it matters: A temporary API problem need not stall or immediately fail the conversation.
• Model-readable failure responses: Describe what an MCP tool should return on each error path and why raw exceptions or unclear messages are insufficient.
  Why it matters: Clear tool errors give the model something useful to work with when a call fails.

Key terms: timeouts, retry logic, exponential backoff, transient network error, error path, raw exceptions, structured response, MCP tools

7.9 Beyond tools: Production agent harnesses and OpenClaw

The section introduces the agent harness as the component that makes MCP tools useful to an agent.

• Agent Harness and Tool Use: Explain why an MCP tool alone is inert and what role an agent harness plays in using it.
  Why it matters: Building a tool is different from building the agent system that can use it.

Key terms: MCP tools, agent harness

7.9.1 Why harnesses matter

This section explains how an agent harness makes an LLM operational by managing tools and state while keeping code execution isolated.

• Harness capabilities around the model: Explain how a harness turns a prompt-and-response LLM into an agent by adding session and state management, memory, tools, and channels for writing results back to systems.
  Why it matters: It distinguishes a capable agent system from a model that only returns text.
• Control and compute separation: Distinguish the harness’s control responsibilities from the sandbox’s execution responsibilities, and explain why credentials remain in the harness and how the system handles a sandbox crash.
  Why it matters: Separating control from execution protects sensitive data and makes execution failures recoverable.
• Harness coordination of MCP tools: Explain the place of MCP tools in the harness architecture and why the surrounding scaffolding, rather than a particular model, defines the operational system.
  Why it matters: Reliable tool use depends on the system coordinating actions, not just on the model or the availability of tools.

Key terms: harness, session and state management, memory mechanisms, tool system, output channels, control plane, compute plane, sandbox, checkpoint, MCP tools

7.9.2 Designing agent-legible environments

The section explains how to make an agent’s working environment legible so it can find instructions, use information, respond to failures, and work reliably.

• Agent legibility over model effort: Explain why improving an agent’s environment and making missing capabilities legible can be more effective than asking the model to try harder.
  Why it matters: It shifts debugging from blaming the model to improving what the agent can access and understand.
• Concise maps and discoverable details: Describe why agent instructions should provide a short map to focused, discoverable details rather than one exhaustive file.
  Why it matters: Focused guidance leaves room for the task while still letting an agent find instructions when needed.
• Accessible records and structured outputs: Explain why important project knowledge should be discoverable in the repository and why MCP tools should return structured outputs.
  Why it matters: Discoverable records and parseable results let agents use information that would otherwise be invisible or difficult to act on.
• Mechanical rules and actionable errors: Describe how linters, structural tests, and remediation messages help agents follow architectural rules.
  Why it matters: A check can enforce a rule repeatedly, and a useful error tells the agent what to change next.
• Legible technology choices: Justify favoring stable, well-documented, composable technologies and, sometimes, a tested simple implementation over an opaque dependency.
  Why it matters: Technology choices affect whether future agent runs can understand and safely modify the system.

Key terms: agent legibility, environment, AGENTS.md, docs/, structured skills files, MCP tool descriptions, repository, system of record, versioned artifacts, structured JSON

7.9.3 The security gap

This section explains why production agents need security boundaries around their tools and execution environments, not just well-designed tools.

• Harness and sandbox security boundary: Explain why separating the harness from the sandbox is a security pattern for agents: tools can expose systems to attacks, while credentials, billing, and audit logs should stay outside the environment where model-generated code executes.
  Why it matters: A useful tool can also become a route to sensitive systems if execution is not isolated.
• Layered production agent defenses: Describe why good tool design alone is insufficient for production agents, and how input validation and structured error handling sit alongside harness boundaries, isolated execution, and failure-surviving state management.
  Why it matters: Reliable tools still depend on the boundaries and failure handling of the system running them.
• Agent adoption security gap: State the contrast the section draws between widespread agent adoption or deployment plans and organizations’ security approval or readiness.
  Why it matters: The gap explains why security boundaries matter for agents being put into use now.

Key terms: harness/sandbox separation, prompt-injection, data-exfiltration, MCP tools, attack surface, input validation, structured error handling, harnesses, sandboxes, state management

7.10 Summary