---
title: "Build a small on-device MCP server"
lesson_id: "03"
---

# Build a small on-device MCP server

- **Lesson ID:** 03
- **Goal:** Write a Swift actor that answers the three MCP methods and stays free of Foundation Models.
- **Human lesson:** [03-on-device-mcp-server.html](03-on-device-mcp-server.html)

## Prerequisites

Lesson 02, or the ability to read the three JSON-RPC methods.

## Inputs, outputs, and artifacts

- **Inputs:** A tool registry and JSON-RPC requests.
- **Outputs:** initialize, tools/list, and tools/call handlers.
- **Artifacts:** Swift actor sketches and progressive .flow diagrams.

## Agent build steps

1. Register tools as name, description, schema, and async run.
2. Handle initialize, tools/list, and tools/call.
3. Return JSON-RPC errors for unknown methods and unknown tools.
4. State that iOS should use an in-process actor, not a stdio child.
5. Link [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/).

## Constraints

iOS 27 or later, or macOS 27 or later, and Xcode 27. Plain spoken English. No metaphor, quizzes, Mermaid, or em dashes. Do not invent a first-party Foundation Models MCP adapter. Show raw JSON-RPC 2.0. Confirm Tool and DynamicGenerationSchema names in the installed SDK docs.

## Key concepts

- An `MCPServer` actor handles initialize, list, and call.
- Each tool has a name, description, input schema, and async handler.
- `tools/call` returns content with `isError`.
- The server speaks JSON-RPC only. It does not import Foundation Models.

## Takeaways

- Keep the server as an actor so calls do not overlap.
- Return a JSON-RPC error for an unknown tool and keep that rule.
- On iOS 27 prefer an in-process actor. macOS can use XPC.

## Acceptance checks

- The server does not import Foundation Models.
- All three methods are handled.
- Sibling links, progressive .flow diagrams, and the Agent brief link are present.
- [ ] Proceed to [lesson brief](04-client-maps-to-tools.llms.md).