---
name: Talk to tools with MCP
description: >-
  Teach an intermediate Edge FDE how to add tools to an Apple AI app through a
  raw JSON-RPC MCP server and client, then map those tools into Foundation
  Models without rewriting the chat loop.
---
# Talk to tools with MCP

Use this course to plug new tools into a Foundation Models chat loop. The reader
already knows a `LanguageModelSession` can call Swift `Tool` types. Keep the
words simple. Show the raw JSON-RPC messages. Do not invent a built-in Apple
MCP adapter for Foundation Models.

## End-to-end agent recipe

1. Start with [lesson 01](01-why-mcp-next-to-tools.llms.md). Split Foundation Models `Tool` from MCP. State the business value: add a tool without rewriting `respond`.
2. Use [lesson 02](02-raw-json-rpc.llms.md) for JSON-RPC 2.0, `initialize`, `tools/list`, and `tools/call`.
3. Use [lesson 03](03-on-device-mcp-server.llms.md) for an in-process Swift MCP server on iOS 27 or macOS 27.
4. Use [lesson 04](04-client-maps-to-tools.llms.md) for the client and the map into `Tool` with `DynamicGenerationSchema`.
5. Use [lesson 05](05-plug-a-tool.llms.md) to register one new tool and keep the same chat loop.
6. Keep these links exact: [Run tools in a safe box](../on-device-sandboxed-tools/), [Stop prompt attacks and leaks](../on-device-guardrails/), and [Core AI vs Core ML vs MLX](../core-ai-vs-core-ml-vs-mlx/).
7. Cite [the MCP specification](https://modelcontextprotocol.io/specification), [Foundation Models](https://developer.apple.com/documentation/foundationmodels), and [WWDC26 session 242](https://developer.apple.com/videos/play/wwdc2026/242/) when a source is needed.
8. Use the human HTML pages for the reader. Use the `.llms.md` briefs for agent steps and acceptance checks.

## Constraints

- Plain spoken English for a non-native reader.
- Literal sentences. No metaphor, no flourish, no quizzes.
- Do not use em dashes.
- Use no Mermaid. Build progressive `.flow` diagrams in HTML.
- Target iOS 27 or later, or macOS 27 or later, and Xcode 27.
- Teach the server and client in Swift. Do not use Python for the on-device MCP loop.
- Do not claim Foundation Models speaks MCP by itself.
- On iOS, keep the server in-process or in an XPC helper. Do not require stdio child processes.

## Key concepts

- MCP lists and calls tools over JSON-RPC 2.0 at runtime.
- Foundation Models `Tool` types are compile-time. Your bridge joins the two.
- `LanguageModelSession` stays the chat loop.
- On iOS 27 use an in-process Swift actor or XPC. There is no built-in Apple MCP adapter.

## Takeaways

- You can plug new tools into an Apple AI app without rewriting the chat loop.
- You can speak MCP in Swift and keep `session.respond(to:)` as the only chat entry point.
- Your bridge is the only join between the model and the server.

## Acceptance checks

- Every human lesson HTML has **Key concepts** and **Takeaways** sections before lesson-nav. The course home has the same two headings for the whole course.
- Five human lessons exist with the requested basenames.
- Five matching `.llms.md` briefs exist and link to their human HTML pages.
- Every human lesson has its Agent brief link and the three sibling-course links.
- The course index lists all five lessons, the course SKILL.md, and all five briefs.
- Diagrams are progressive HTML `.flow` elements. There is no Mermaid, no em dash, and no quiz.

## Environment setup

Xcode 27 on a Mac. New SwiftUI app, iOS 27 or macOS 27. Add the Foundation Models framework. The JSON-RPC samples are sketches of the public MCP spec, not a project you must run.