Skip to content
Hands-on Coding Assistants

Part 4 — Build the Harness Chapter 22

MCP (Model Context Protocol)

In this chapter

You can explain the Task API’s validation convention by reading its tests. Suppose the same convention came from a shared service outside the repository. The agent would need a way to find and call that service. The Model Context Protocol, or MCP, lets OpenCode discover tools supplied by a server and invoke them with structured input.

Start a new exercise branch at lab-start. The lab includes tools/project-context.mjs, a small local server started over standard input and output. Its one tool returns a fixed sentence about validation. It needs no network service or key.

git switch -c context-tool lab-start
npm run test:mcp

The smoke test starts the process and checks its sample replies. Use that result to diagnose process failures before you bring in the model. The MCP specification describes a client that negotiates initialization before normal operation. You can verify a real client connection separately.

Connect the server in OpenCode

Merge this top-level mcp block into the existing opencode.jsonc. Preserve the existing permissions. Disabling Code Mode for this server makes the individual tool call visible.

{
  "mcp": {
    "servers": {
      "project_context": {
        "type": "local",
        "command": ["node", "tools/project-context.mjs"],
        "codemode": false
      }
    }
  }
}

From the repository root, run opencode mcp list and check for project_context with a connected status. If OpenCode 2.3.2 reports No MCP servers configured on the first request, check your working directory and the smoke test, then retry in the same background service. That version has a cold registry issue. Use the normal service for this exercise to give discovery time to finish.

Ask the model to call it

Start a fresh Plan session.

Call project_context_get_task_conventions. Report its response and show
which test in test/app.test.ts checks that convention.

Look for a completed tool call and compare its response with the source. It should mention returning HTTP 400 and preserving the task list. The model can give you those facts by reading the repository. Look at the call itself to distinguish that answer from an integration that worked.

For one comparison, append a denial to permissions.

{ "action": "project_context_get_task_conventions", "resource": "*", "effect": "deny" }

In a new session the tool should be unavailable or blocked even if the server is listed as connected. Undo the rule and verify a successful call again. Record the process, discovery, and call results separately. Add a production MCP connection when its controlled lookup makes the workflow easier to verify.

References