AICON MCP Tutorial

Workshop repo for a 3-hour tutorial on tool calling, MCP, ToolHive hosting, and remote/authenticated MCP.

The tutorial uses one shared agent harness and evolves the way GitHub capabilities are exposed:

1. Direct provider-style tool calling.
2. Local MCP servers.
3. ToolHive-hosted MCP servers.
4. Remote/authenticated MCP (GitHub's hosted server, behind OAuth).

By default, attendees use a fake GitHub integration backed by local data, so the tutorial runs without external service setup. Instructor demos can switch to real GitHub through .env — either the gh CLI or the REST API (GITHUB_MODE=gh or api).

Repo Shape

aicon_mcp_tutorial/
  harness/       shared host and agent loop code
  integrations/  shared GitHub capabilities (fake + real backends)

parts/
  01_direct_tool_calling/
  02_local_mcp/
  03_toolhive/
  04_remote_oauth/

solutions/       reference answers for each part's exercise
cluster/         kind cluster install/uninstall (Parts 3-4)

Setup

cp .env.example .env
uv sync

The default .env.example values use fake GitHub so the tutorial can run without external service setup; only OPENAI_API_KEY is required.

Start here

Work through the parts in order — each has its own README:

1. parts/01_direct_tool_calling/
2. parts/02_local_mcp/
3. parts/03_toolhive/
4. parts/04_remote_oauth/

Slides

Post-tutorial slide deck (optional, for anyone who wants the talk-track): AICON MCP Tutorial slides.