OpenCode + MCP: find a café you can work from

Build toward one question:

Find cafés in BGC with Wi-Fi, power outlets, matcha, and Spanish latte.

The finish line is an actual MCP call that checks every loaded BGC record and returns supported matches with their evidence. Both drinks are required. Unknown does not mean yes.

This repo is the companion to the AWS MCP + OpenCode talk. The café exercise runs locally; it needs no AWS account, cloud deployment, or café API key. OpenCode uses your own configured model access.

Get the repo

Install Git, Node.js 22.19 or newer, and OpenCode. OpenCode must already be able to answer a short question with your chosen model before the timed workshop starts.

git clone https://github.com/dayvough/opencode-mcp.git
cd opencode-mcp
npm ci --ignore-scripts
npm run doctor

Already cloned it? Run git pull --ff-only, then npm ci --ignore-scripts. Commit or stash your own edits first if Git reports a conflict; do not discard your work to follow the workshop.

Run every command below from the repo root. You do not need to change folders between steps. The examples use JavaScript modules, so there is no compile step.

Follow the folders

Each folder contains the instructions and code for that stage. These are working checkpoints: inspect the small piece that changes, run it, then try the suggested edit. You can jump to the next checkpoint if you fall behind.

Folder	What you do	Command	Time
00 — Setup	Clone, install, check your tools	`npm run doctor`	Before the timer
01 — Read the data	See the café records and their unknowns	`npm run step:01`	0–2 min
02 — Add the filter	Turn the question into explicit rules	`npm run step:02`	2–6 min
03 — Create the MCP tool	Expose the filter through the SDK	`npm run step:03`	6–9 min
04 — Inspect the call	Discover and call the tool directly	`npm run step:04`	9–12 min
05 — Connect OpenCode	Add the server to your client	`npm run step:05`	12–15 min
06 — Check the answer	Compare returned IDs with known answers	`npm run step:06`	15–18 min
07 — Change a record	Prove the same call reflects changed data	`npm run step:07`	18–20 min

Step 3 waits for a client. Press Ctrl+C before moving on. Step 4 launches its own server process, makes real MCP requests, and exits.

Ask OpenCode

After step 5, restart OpenCode from this directory:

opencode mcp list
opencode

Ask:

Use the cafes MCP tool find_cafes. Find BGC cafés with Wi-Fi and customer-use power outlets. Require both matcha and Spanish latte. Show the returned café IDs, sources, and source dates. Keep unknowns separate from supported matches.

OpenCode may show the tool with a server prefix, such as cafes_find_cafes. Inspect the tool call and its arguments. A confident paragraph without the intended tool call does not pass this exercise.

What is happening?

flowchart LR
  A[Your question] --> B[OpenCode chooses tool and arguments]
  B -->|MCP tools/call| C[find_cafes]
  C --> D[Read saved café records]
  D --> E[Apply the filter in code]
  E --> F[Return matches and evidence]
  F --> B

On connection, the client discovers the tool with tools/list. When the model chooses it, the client sends tools/call. MCP is the shared interface. The filtering rules come from our code; the quality of the facts comes from the dataset and its sources.

OpenCode can also read files and use other tools without MCP. Keep the model, question, and other access the same when comparing the two setups. Our addition is a named, reusable search with validated inputs and checkable results.

Two datasets, two purposes

The real BGC snapshot contains source-backed branch records. The default tool reads data/bgc.json on every call. It is a saved snapshot, not a live scraper or a complete list of every café in BGC.
The test fixture contains seven explicitly fictional cafés. Their known answers let us prove that missing requirements, unknowns, conflicts, and changes are handled properly. The default server never loads these records.

Read the data notes before presenting a real café as a match. A delivery menu is not proof of current stock; a customer Wi-Fi report is not a speed test or an official policy.

For the presenter

npm test checks the filter, data provenance, actual MCP discovery/calls, invalid inputs, and a record change through the same running server. It does not test a model's natural-language answer. Complete that last check in OpenCode during rehearsal.

Code and original workshop explanations are available under the MIT license. Linked source material retains its own terms.

After the workshop

Try the optional challenges. Compare drink rules, inspect failure cases, add a drink, or build an explanation tool. These are separate from the timed workshop.